[{"content":"What are Game Server Services? Game development has become increasingly complex over the last 30 years. The Unity / Unreal Engine general-purpose game engines have revolutionized the industry. In the past, game developers had to spend a significant amount of time creating the infrastructure for games, including graphics, asset management, and sound, before they could begin creating content. The creation of these environments was done independently for each title, and development proceeded with insufficient sharing of information between titles. As a result, the wheel was constantly reinvented between companies and projects. A general-purpose game engine solves these problems and allows game developers to start creating content immediately. By using the same technology stack across companies and projects, we now have a development environment that allows for greater staff mobility without sacrificing productivity. However, the starting point for these innovations was more than a decade ago. The game environment has changed dramatically over the past decade. One of the most significant changes is the demand for game development that relies on online capabilities. Online game support for general-purpose game engines is inadequate, and game server development, like game engine development in the past, is done independently by each company and each project. This lack of productivity is evident, now that it has become commonplace to develop on general-purpose game engines. Game Server Services was created to solve this problem and improve the efficiency of your general-purpose game server development. What makes Game Server Services different from other server solutions? We offer a server solution to monetize your game long term. This can be called Game as a Service or a solution to support what we call Live Gaming. A typical game genre for Game as a Service would be MMORPG. If you think that Game as a Service only applies to a few game genres, you are wrong. Game server services originated in Japan. Before the advent of smartphones, the trend of “social games”, which started with Facebook games, blossomed in Japan and became a huge business. Browser-based social games have left the hands of social networks and the social element has completely faded away, but the game mechanics invented have become the backbone of smartphone game mechanics. Have you heard of Genshin Impact? Genshin Impact is developed in China, but it takes the game mechanics that Japanese social games have developed and sublimates them into something that can be used globally. Game Server Services is a solution that can be used to develop games like Genshin Impact, where competitive gaming is not the focus of the game, but network functionality plays an important role. What features are provided for Game as a Service? Other companies’ solutions are based on storing player data as binary data. This method is flexible, but it has its problems. Other companies’ solutions are based on storing player data as binary data. This method is flexible, but it has its problems. First, it is difficult to analyze the data; to achieve Game as a Service, the total number of resources distributed and consumed in the game must be properly analyzed to maintain a healthy environment. Second, cheating is possible, and to achieve Game as a Service, players’ resources must be properly managed to maintain order in the game world. Game Server Services puts a lot of effort into designing and providing microservices for each function in the game. For example, we provide Story progression management Inventory Collections Avatar, equipment, party organization Experience and level Usage limits Event Schedule Management The ability to analyze story progress is critical for Game as a Service. What if only 1% of players have completed all the stories, and you spend a lot of effort developing additional stories? This is a waste of time. Before adding more stories, we need to analyze why people have not completed the stories and improve the game so that more people will complete the existing stories. Inventory management is also important. This should be managed on the server so that players do not lose their items, but it is also important for the developer to know the total amount of items being distributed in the game and how much is being consumed. Which items do players need the most? Is there a surplus of in-game currency that has lost its purpose? By analyzing this situation, you can motivate players by including the most needed resources in event rewards or by introducing content that allows players to consume more of the excess resources. Thus, Game as a Service is essential for analyzing data for a healthier in-game economy. However, this will not be possible if player data is stored in binary form. Basic Terminology Here are some important terms that appear frequently when using GS2. GS2-Identifier A service that manages “users” and “access permissions (policies)” for accessing GS2 resources, and the “credentials (client ID/secret)” required for API calls. GS2-Deploy A service that automatically builds and manages GS2 resources (namespaces, master data, etc.) using template files in YAML format, similar to AWS CloudFormation. Namespace An independent space created within each service to separate data and settings. For example, you can create and use separate namespaces for different purposes such as “development” and “production”. Are you ready? The content you should read next depends on your interests. I want to know more about what Game Server Services can do I want to know more about the development process using Game Server Services I want to know more about Game Server Services fees I want to know more about Game Server Services extensions I want to download the SDK for Game Server Services I want to see the Game Server Services API reference","lang":"en","section":"overview","summary":"What are Game Server Services? Game development has become increasingly complex over the last 30 years. The Unity / Unreal Engine general-purpose game engines have revolutionized the industry.\nIn the past, game developers had to spend a significant amount of time creating the infrastructure for games, including graphics, asset management, and sound, before they could begin creating content. The creation of these environments was done independently for each title, and development proceeded with insufficient sharing of information between titles.","title":"About Game Server Services","url":"/overview/"},{"content":"GS2-Identifier is a mechanism to manage credentials (authentication information) and access privileges to access GS2 services. Authority management for access to each service is performed for each GS2-Identifier user (hereinafter referred to as “user”). GS2 assigns a security policy to each user, which defines what GS2 services the user can use. GS2 uses the credentials to authenticate the accessing user and returns a project token. The game application/management tool uses this project token to access each service. Detailed permission settings are defined in the security policy, which is assigned to each user. Users The following is an overview of the data structure a user has class User { +userId +name : } class Identifier { +clientId +clientSecret : } class Password { +hashedPassword : } class AttachedSecurityPolicy { +securityPolicyId : } class SecurityPolicy { +policyDocument : } User \"1\" *-- \"many\" Identifier User \"1\" --- \"1\" Password User \"1\" *-- \" Security Policy The following policies have been predefined in the security policy. Security Policy Name Description AdministratorAccess Permission to use all APIs ApplicationAccess Permission to call only APIs that do not lead to cheating DeliveryAccess Permission required for GS2-Distributor to perform resource overflow processing UnauthenticatedAccess Authority to perform only the processing (including login processing) necessary to perform version checks (GS2-Version). AdministratorAccess policy is the authority to access all GS2 services. The ApplicationAccess policy, which is intended to be embedded in a game application, is a policy that allows access to all GS2 services. The ApplicationAccess policy, which is assumed to be used in a game application, is set so that API calls that can manipulate the server leading to cheating are not allowed. Security Policy Format Security policies are written in JSON format. Statements contain the Effect, Actions, and Resources elements. The * (asterisk) represents a wildcard. The simplest security policy is shown in the example. This security policy says that all operations are allowed on all services and APIs. APIs. Effect Specify whether access to the API is allowed or not in this policy. Actions The security policy shown in the example allows any operation on the GS2-Inbox service. The user assigned the security policy in this example has no access to any services other than GS2-Inbox. The * (asterisk) represents a wildcard. Enumerating Actions Actions can enumerate actions, specifications of methods that can or cannot be accessed and executed. Actions can be enumerated. Specify the methods listed in the reference for each service. Put a : (colon) in between, e.g. [service name]:[method name]. To specify a service name, use Gs2Inbox without the - (hyphen), and the name of each service should be appended to Gs2, as in “Gs2Inbox”. The method name should be SendMessage with the first letter capitalized (upper camelCase). Resources This variable specifies the range of resources affected by this policy. Resources lists the GRNs of the resources whose operations are to be allowed or denied. As with Actions, leading and trailing wildcards are allowed. In this example, only namespace-0001 has SendMessage-enabled permissions. Determine security policy A user can assign up to 10 security policies. After processing with And for actions for which Allow is specified in Effect, the API can be called except for those processed with And for actions for which Deny is specified in Effect. In other words, if both Allow and Deny are described, Deny takes precedence.","lang":"en","section":"articles","summary":"Access Control for GS2 API\n","title":"Access Control","url":"/articles/tech/identifier/"},{"content":"Performs account creation and login process. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Account GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Account/initialize_account_template.yaml Project details Open the project and you will see the above. When I run it, at first it shows “Not Logged-in”. After waiting for a while, the display will change to “Logged-in” and the user ID of the logged-in user will be shown in the lower right corner. Project Description Notice the hierarchy of the scene. The Game Object with the GS2 logo is assigned a UI Kit component. Canvas/View You can see that two components are allocated. Gs2AccountLoggedInEnabler . In the Add Component menu, you can add the following paths. This component can enable or disable GameObjects depending on the login status. If you specify a GameObject as Target without checking Logged In, If you specify a GameObject in Target without checking Logged In, the GameObject specified in Target will be enabled when the user is not logged in, and disabled when the user is logged in. Conversely, if the Logged In checkbox is checked, the GameObject specified as Target will be enabled when the user logs in. If “Logged In” is checked, the GameObject specified as Target will be enabled when logged in, and disabled when not logged in. In this sample, “NotFoggedIn” is enabled when not logged in, and “LoggedIn” is enabled when logged in. Canvas/View/LoggedIn Again, you can see two components assigned. Gs2AccountOwnAccountContext Specifies the context to be used by the child elements of this GameObject. Gs2AccountOwnAccountContext specifies the context for the currently logged in GS2-Account account. A ScriptableObject called “OwnAccount” is specified. If we check the ScriptableObject specified in OwnAccount, If you check the ScriptableObject specified in OwnAccount, you will see that a ScriptableObject representing your own account in the namespace named game-0001 is specified. Gs2AccountOwnAccountFetcher . Gets and holds information about the account specified in Gs2AccountOwnAccountContext. Canvas/View/LoggedIn/UserId Gs2AccountAccountLabel . Outputs the account information obtained by Gs2AccountOwnAccountFetcher of the parent node in the format specified by Format. In the sample, {userId} is specified, so it is replaced with your own user ID. A placeholder can be added to the Format by clicking the Add Format Parameter button. The formatted string is passed to the OnUpdate(String) event. In this case, the value is reflected in the Text set to the same GameObject. Process/Gs2AutoLogin The prefab that executes the login process is set. A prefab that executes such an API can be added from the context menu. AutoLogin . Specifies the namespace of the GS2-Account used to create and login to the account and the encryption key of the GS2-Key used for the login process. OnAutoLogin sets the event handler to be called when login succeeds. By default, it disables its own GameObject so that the login process does not run multiply. OnError sets the event handler to be called when login fails. Here, a function is called to output the contents of the error.","lang":"en","section":"articles","summary":"sample implementation of GS2-Account functionality using GS2 UIKit for Unity","title":"Sample of Account(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/account/"},{"content":"Implement text chat functionality. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Chat GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Chat/initialize_chat_template.yaml Project Description Open the project and you will see the above. When executed, a screen will be drawn with only a text input field and a submit button at the bottom of the screen. Try typing “test” and sending it. Then the date and time of the submission and the message will be displayed. Try again, this time typing “test2” and submitting. The list will also reflect the posted message. Project Description Note the hierarchy of the scene. Canvas/ChatWindow Gs2ChatRoomContext . Specifies the chat room to be handled by the node under this GameObject. This sample specifies a room named room-0001 in the namespace chat-0001. Canvas/ChatWindow/Messages/…/Content Gs2ChatMessageListFetcher . Get a list of messages in the room specified by RoomContext. Gs2ChatMessageList . Generates a list of messages obtained by Gs2ChatMessageListFetcher by assigning them to the specified prefab. Maximum Items specifies the maximum number of prefabs to be generated. This time, Message in the child node is specified as a prefab. If a GameObject specified as a prefab exists in the scene, the GameObject will be disabled and the number of GameObjects specified in Maximum Items will be created in addition to the GameObjects specified as prefabs. Canvas/ChatWindow/Messages/…/Content/Message Gs2ChatMessageContext . Specifies the message to be handled by the node under this GameObject. The content of the context is assigned by Gs2ChatMessageList. Gs2ChatMessageFetcher . Gets the message specified by MessageContext. Canvas/ChatWindow/Messages/…/Content/Message/Text Gs2ChatMessageLabel . Outputs the message content retrieved by Gs2ChatMessageFetcher. This time, the format is specified to be formatted as “{message posting time}:{message posting minute} {message payload}”. The formatted value is specified in Format. The formatted value is called back by OnUpdate(String), and the value is reflected in the Text component. Canvas/ChatWindow/Input/Send/Gs2ChatMessagePostAction Gs2ChatMessagePostAction . Prefab that executes the process of posting a message. It can be added from the context menu here. Specify the content of the message to be posted in Category and Metadata to activate prefabrication. The prefab is therefore disabled by default and activated when the Send Message button is clicked. OnPostComplete(EzMessage) can be used to specify the callback when the message has been successfully sent. Here, the process is set to invalidate itself and initialize the text input field of the chat message. Process/Gs2AutoLogin The prefab that executes the login process is set here. Sample of Account , please refer to the explanation there. Let’s Challenge How do I disable the “Send Message button” until the login process is complete? The way to branch by whether the login process is completed is sample of Account . Please think about how it could be done.","lang":"en","section":"articles","summary":"sample implementation of GS2-Chat functionality using GS2 UIKit for Unity","title":"Sample of Chat(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/chat/"},{"content":"Game Server Services is not a server solution We are going to talk about something that contradicts the name of our service. When we designed Game Server Services, our primary goal was to make the game developer’s experience the best it could be. How do game developers feel about network features? It makes the game fun. It’s a given for today’s games. Necessary for the long-term business of the game. On the other hand, how do game developers feel about server development? It’s a pain in the neck. It seems like a lot of work. I don’t want to go near it. Game Server Services bridges this gap. Using a server is hard! A server is required to implement networking functionality. However, server developers make APIs, not SDKs. So who programs the communication process with the server API? Game developer . Game Server Services tries to make the SDK as game developer friendly as possible, to make the communication process less tedious and more like a standard library. Typical efforts include SDKs with a caching mechanism that reduces the number and duration of server communications. SDKs that integrate with Unity / Unreal Engine to enable no-code development Data analysis and customer support is hard work! When you implement Game as a Service, you need to analyze data about how players play your game. When you build a new server, you also need to build a data analysis system. The same is true for customer support. In a long-term game, customer support will have to deal with more and more cases. What customers say may not always be true. Behavior logs need to be checked to see if what the customer is saying is true, and the issue needs to be escalated to development. If this mechanism is poor, all requests will be sent to the game developer and game development will be compromised. Game Server Services addresses this by providing data analysis and customer support tools. Serverless and Microservices When game developers manage their own servers, they tend to get bogged down in tasks unrelated to the essence of the game, such as server monitoring, scaling, and OS updates. GS2 adopts a serverless architecture, so developers do not need to be aware of server management. In addition, since functions are provided as independent microservices , it is possible to select and combine only the necessary functions. Integrated Development and Operation Environment for Network Features Game Server Services is not just a “collection of APIs,” but provides a comprehensive environment that supports everything from development to operations. graph LR subgraph \"Game Server Services (GS2)\" SDK[GS2 SDK] API[GS2 Microservices] Console[Management Console] Analytics[Analytics / Logs] end Developer[Game Developer] --\u003e SDK Developer --\u003e Console Developer --\u003e Analytics GameClient[Game Client] --\u003e SDK SDK --\u003e API API --\u003e Analytics In short Game Server Services is the foundation of the game server, making it easy for game developers to support the network, and Game Server Services provides a complete development and operating environment for network features that also provides a mechanism for subsequent data analysis and customer support.","lang":"en","section":"overview","summary":"About the game development environment that Game Server Services aims to create.\n","title":"Concept of Game Server Services","url":"/overview/concept/"},{"content":"Once the game specifications have been determined, it is necessary to consider how to implement them. GS2 provides microservices that can be used to implement various game specifications. Please refer to the following document for a description of the types of microservices provided by GS2 and the role of each microservice. Introduction to Microservices Game Server Services offers paid support to help you with your design. When you sign up for paid support, GS2 staff will work with you to understand your game specifications and how best to apply GS2’s microservices. support menu","lang":"en","section":"overview","summary":"Design to achieve game specifications using GS2.\n","title":"Design","url":"/overview/workflow/architect/"},{"content":"Implement the Pictorial Book function. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Dictionary GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Dictionary/initialize_dictionary_template.yaml Project Description Open the project and you will see the above. Run it and you will see the availability of the 5 characters from A to E. Since none of the characters have been obtained now, they are all grayed out. The buttons to obtain each character are placed at the bottom of the screen. First, let’s press the “A” button. Having obtained the “A” character, it will be displayed in color and the time of obtaining it will be displayed. Let’s press the “C” button as well. The “C” character will also be displayed in color. Project Description Note the hierarchy of the scene. Canvas/DictionaryWindow Gs2DictionaryNamespaceContext Specifies the namespace to be handled by the node under this GameObject. This time, dictionary-0001 is specified. Canvas/DictionaryWindow/Dictionary/…/Content Gs2DictionaryEntryModelListFetcher Gets the entry model list for the namespace specified by NamespaceContext. Gs2DictionaryEntryModelList Generates the entry models obtained by Gs2DictionaryEntryModelListFetcher by assigning them to the specified prefab. Specify the maximum number of prefabs to generate for Maximum Items. This time, the Entry in the child node is specified as the prefab. If the GameObject specified as a prefab is in the scene, that GameObject will be disabled and the number of GameObjects specified in Maximum Items will be created in addition to the GameObjects specified as prefabs. Canvas/DictionaryWindow/Dictionary/…/Content/Entry Gs2DictionaryEntryModelContext Specifies the entry to be handled by the node under this GameObject. The content of the context is assigned by Gs2DictionaryEntryModelList. Gs2DictionaryEntryModelFetcher Gets the model for the entry specified by Gs2DictionaryEntryModelContext. Gs2DictionaryOwnEntryFetcher Gets the own entry of the entry model specified in Gs2DictionaryEntryModelContext. Gs2DictionaryEntryEnabler Enables a GameObject to display the date and time it was obtained, depending on the Entry’s loading status. If the Entry is not obtained, it will not be Loaded and will only be enabled if it is obtained. Gs2DictionaryEntryModelEnabler . Enables a GameObject that displays the name of the entry depending on the EntryModel loading status. Canvas/DictionaryWindow/Dictionary/…/Content/Entry/Icon Displays the icon image of the character. However, the type of image displayed must vary depending on the entry to be listed. Gs2DictionaryEntryModelNameEnabler Enables or disables GameObjects according to the name of the entry model obtained by Gs2DictionaryEntryModelFetcher. In the sample, five entry models are placed, and only the entry node corresponding to “A” to “E” is set to be enabled. Canvas/DictionaryWindow/Dictionary/…/Content/Entry/Icon/A GameObjects “A” to “E” are set, but in principle they have the same structure. It branches in the same way as the part that displays the date and time of acquisition, enabling Active if it has been acquired and Disabled if it has not been acquired. Canvas/DictionaryWindow/Dictionary/…/Content/Entry/Icon/A/Active Canvas/DictionaryWindow/Dictionary/…/Content/Entry/Icon/A/Disabled In Disabled, GrayScaleMaterial is specified for Material, which uses shaders to gray out the image. Canvas/DictionaryWindow/Dictionary/…/Content/Entry/Name Displays the name of the entry model. Gs2DictionaryEntryModelLabel . Formats the contents of the entry model in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/DictionaryWindow/Dictionary/…/Content/Entry/AcquiredAt Displays the date and time the entry was obtained. Gs2DictionaryOwnEntryLabel . Formats the entry content in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/DictionaryWindow/Input/Acquire A Gs2ExchangeRateModelContext Sets the GS2-Exchange exchange rate at which the entry will be made available. Here, the A-rate model in the exchange-0004 namespace of GS2-Exchange is set to exchange. Canvas/DictionaryWindow/Input/Acquire A/Gs2ExchangeExchangeAction You can add a prefab from this context menu. By specifying the exchange quantity in Count and activating the prefab, the exchange rate specified in Gs2ExchangeRateModelContext will be executed. OnExchangeComplete(String) can be set to a callback when the exchange process is successfully completed, and disables itself. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Dictionary functionality using GS2 UIKit for Unity","title":"Sample of Dictionary(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/dictionary/"},{"content":"GS2 responds to errors according to certain rules. By understanding these rules, you will be able to resolve errors quickly. Example of an error message [{\"component\": \"progress\", \"message\": \"quest.progress.progress.error.notFound\"}] section description component Indicates the target where the error occurred, and contains the member name and method name. message Details of the error location and keywords that describe the error. serviceName . component .error. errorType Major error types major error content description failed Processing failed. invalid Illegal parameter. require Missing required argument. tooLong Argument is too long. tooMany Too many array elements. exists Already exists. duplicate duplicate, already exists. notFound Not found. notMatch No match was found. Types of Exceptions Errors are classified to some extent by SDK, and the type of exception sent out varies. All exceptions inherit from Gs2Exception , and you can determine whether to retry by referring to the following properties: RecommendRetry : Errors for which a manual retry should be considered, such as displaying a “Retry” button to the user. RecommendAutoRetry : Errors that are safe for the system to retry automatically without notifying the user. Exception Error Content Status Code RecommendRetry RecommendAutoRetry BadRequestException Bad request content. 400 UnauthorizedException Authentication failed. 401 QuotaLimitExceededException Quota limit exceeded. 402 ✔ NotFoundException The object could not be found. 404 ConflictException Processing conflict. 409 ✔ InternalServerErrorException An error occurred on the server. 500 ✔ ✔ BadGatewayException The server received an invalid response. 502 ✔ ✔ ServiceUnavailableException A transient error occurred in the service. 503 ✔ ✔ RequestTimeoutException Request timed out. 504 ✔ ✔ UnknownException Unknown exception occurred. Exceptions where RecommendRetry is true are errors that may occur due to server conditions, although the request parameters are normal. When such errors are detected, it is recommended to retry. It is strongly recommended to implement a timeout after a certain number of times or a certain amount of time, rather than retrying until success. When retrying, it is recommended that a sleep be inserted between requests, and that the length of the sleep be increased according to the number of retries. For errors that require in-game handling, some microservices define error-specific exception types that inherit from the exceptions enumerated for each microservice. In such cases, error handling can be more easily implemented by using error-specific exceptions. If there are exceptions that represent error-specific errors, please refer to the method descriptions in the API reference. Retrieving Exceptions Occurring on the Client The GS2-CSharp-SDK and GS2 SDK for Unity allow you to retrieve the error message content that occurred in the game engine/framework used for the connection. Exception Error Content Status Code NoInternetConnectionException Failed to connect to the internet. ※ Includes connection errors when socket establishment or DNS resolution fails due to the device being in airplane mode, out of range, or connected to a router but unable to exit the network. 0 　ConnectionException (Unity only)　Failed to communicate with the server. Examples include: the request couldn’t connect, or a secure channel couldn’t be established. 0 　DataProcessingException (Unity only)　An error occurred during data processing. 0 　HttpRequestException (.NET only)　An error occurred during the HttpRequest. 0 Chaos mode GS2 C# SDK and GS2 SDK for Unity include Chaos Mode. When enabled, chaos mode will randomly emit exceptions that require retries at a specified rate. By proceeding with development with chaos mode enabled, error handling in the game can be made more robust. See initialization process for how to enable chaos mode. Implementation Guide For more specific implementation methods and best practices, see Implementation Patterns for Error Handling .","lang":"en","section":"articles","summary":"Common errors that occur when using Game Server Services.\n","title":"Error/Exception","url":"/articles/tech/error/"},{"content":"Implement experience weight and level functionality. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Experience GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Experience/initialize_experience_template.yaml Project Description Open the project and you will see the above. Run it and you will see the current level, level cap, and progress bar like this. At the bottom of the screen, there is a button for operating experience. Let’s add 100 experience with “Add Experience(100)”. Experience has been added and the level has increased from 1 to 3. Let’s add 100 to the experience value again with “Add Experience(100)”. The level has increased to 5 and the level cap has been reached. To make it easier to understand this status, the level value has been changed from black to red. Let’s press “Add Rank Cap” to raise the level cap. The level cap has been raised from 5 to 6. As a result, the current level has not reached the level cap, so the level notation has also been changed back from red to black. Project Description Note the hierarchy of the scene. Canvas/ExperienceWindow Gs2ExperienceExperienceModelContext Specifies the experience model to be handled by the node under this GameObject. In this case, we specify an experience model named Experience in the namespace experience-0001 in GS2-Experience. Gs2ExperienceOwnStatusContext . Specifies the status of itself handled by the node under this GameObject. This time, we specify an experience model named Experience and a property ID named player in the namespace experience-0001 in GS2-Experience. Gs2ExperienceOwnStatusFetcher . Gets the status specified in Gs2ExperienceOwnStatusContext. Canvas/ExperienceWindow/Experience/…/RankValue Gs2ExperienceStatusEnabler . Enables/disables ValueContainer / Slider depending on status loading. Canvas/ExperienceWindow/Experience/…/RankValue/ValueContainer Gs2ExperienceStatusRankValueEnabler . Enables or disables Value / ReachMaxValue depending on whether the status rank has reached or not reached the maximum value. Canvas/ExperienceWindow/Experience/…/RankValue/ValueContainer/Value Gs2ExperienceOwnStatusLabel . The current rank value and rank cap value are formatted in the format specified by Format. The formatted result is called back to OnUpdate(String) and is reflected in the Text component. The Text component here specifies black as the text color. Canvas/ExperienceWindow/Experience/…/RankValue/ValueContainer/ReachMaxValue Gs2ExperienceOwnStatusLabel . The current rank value and rank cap value are formatted in the format specified by Format. The formatted result is called back to OnUpdate(String) and is reflected in the Text component. The Text component here specifies red for the text color. Canvas/ExperienceWindow/Experience/…/Slider Gs2ExperienceStatusProgress . Returns the progress from 0.0 to 1.0 in the current rank until the next rank up experience is reached in the OnUpdate(Single) callback. The value is reflected in Slider.value. Canvas/ExperienceWindow/Input/AddExperience Gs2ExchangeRateModelContext . Sets the GS2-Exchange exchange rate that adds 10 to the experience value. Here we specify an exchange rate named AddExperience in the GS2-Exchange namespace named exchange-0006. Canvas/ExperienceWindow/Input/AddExperience/Gs2ExchangeExchangeAction You can add a prefab from this context menu. By specifying the exchange quantity in Count and activating the prefab, the exchange rate specified in Gs2ExchangeRateModelContext will be executed. OnExchangeComplete(String) can be set to a callback when the exchange process is successfully completed, and disables itself. Canvas/ExperienceWindow/Input/AddExperienceX10 Canvas/ExperienceWindow/Input/AddExperience Sets the GS2-Exchange exchange rate that adds 10 to the experience value as in. Canvas/ExperienceWindow/Input/AddExperienceX10/Gs2ExchangeExchangeAction Set the exchange quantity to 10. Canvas/ExperienceWindow/Input/AddRankCap Sets the GS2-Exchange exchange rate at which to add one rank cap. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"Sample implementation of GS2-Experience functionality using GS2 UIKit for Unity","title":"Experience(GS2 UIKit for Unity) sample","url":"/articles/sample/uikit_project/experience/"},{"content":"GS2 provides several functions as microservices. However, there may be situations where you want to extend the functionality. GS2-Script provides scripting capabilities using the Lua language and can extend the functionality of GS2 microservices. Scripts written in GS2-Script are not invoked at all times, but are executed in response to triggers defined by each GS2 microservice. For example, GS2-Account has the following triggers Create new account Authentication execution Register transfer information Transfer execution For each of these, “synchronous processing” and “asynchronous processing” are available as the timing for script execution. Example of script executed when creating a new account Request Type Description namespace Namespace Namespace account Account Game player’s account Result Type Required Default Value Constraints Description permit bool  Whether to allow creating an account Implementation Example namespace = args.namespace account = args.account result = { permit=permit } Synchronous processing When synchronous processing is set for a trigger, API processing is blocked until script execution is complete. Instead of slowing down the response time of the API for the duration of the script execution, you can “fake” the results of the script or “stop processing”. To give a more concrete example, you can use a script to double the amount of experience gained from a quest, or to cause a response error if the party formed at the start of a quest does not include a certain character. Asynchronous processing When asynchronous processing is set for a trigger, the script is executed asynchronously after the API responds. If you want to implement a ranking based on the number of items owned, you can assign an asynchronous script to the trigger when an item is acquired or consumed. This allows you to register the number of items owned as a score in the ranking without affecting the response time of the API. Asynchronous processing in Amazon Event Bridge GS2 can use the Amazon Event Bridge provided by AWS to implement asynchronous processing. See the separate document for details on using the Amazon Event Bridge.","lang":"en","section":"overview","summary":"How to extend GS2's microservices functionality.\n","title":"Extend","url":"/overview/workflow/coding/extend/"},{"content":"","lang":"en","section":"get_start","summary":"Sample code to implement everything from account issuance to login\n","title":"Full sample code","url":"/get_start/tutorial/coding/all/"},{"content":"Initializing the SDK To start using GS2, you must first initialize GS2-SDK. You can get a GS2 client instance, Gs2Domain , by calling Gs2Client.Create . The parameters required for initialization are as follows. Parameters Argument name Type Description credential BasicGs2Credential credential information region Region GS2 region BasicGs2Credential Specify the “Client ID” and “Client Secret”. These values are managed by GS2-Identifier. Region Specifies the GS2 data center. See region for possible values. Implementation example Chaos mode By calling the SDK initialization process with chaos mode applied, API requests can be made to fail with a certain probability. Development can proceed using clients with chaos mode enabled to ensure robust error handling. Create an account Many GS2 features require players to login by specifying their GS2-Account account information. In order to log in, an account must be created. To create an account, use Gs2Domain::Account::Namespace()::Create . Parameter Argument name Type Description namespaceName string GS2-Account’s namespace name Implementation example Login Now that you have initialized the SDK and created your account, you are ready to login. You can use Gs2Domain::Login to perform the login. As a result, you will get a GameSession object. Many APIs require a GameSession to be passed, which gives you access to the user data of the player who is logging in. Parameters Argument name Type Description authenticator IAuthenticator implementation used for authentication process (GS2-Account) userId string userID password string password IAuthenticator The authentication process is interface-defined and can be implemented without using GS2-Account, replacing it with authentication on your own authentication infrastructure. Gs2AccountAuthenticator Gs2AccountAuthenticator is an authentication implementation that uses GS2-Account and provides sufficient functionality for common use cases. Argument Name Type Description accountSetting AccountSetting Information to authenticate with GS2-Account gatewaySetting GatewaySetting Information for receiving notifications via GS2-Gateway versionSetting VersionSetting Information to check the version with GS2-Version AccountSetting Argument Name Type Description accountNamespaceName string Namespace name of the GS2-Account keyId string Encryption key ID of GS2-Key used for authentication process (if omitted, the default encryption key is used) GatewaySetting Argument Name Type Description gatewayNamespaceName string Namespace name of GS2-Gateway (default namespace is used if omitted) allowConcurrentAccess bool Whether multiple logins with the same user ID are allowed (default: true) VersionSetting VersionSetting can be applied to automatically perform a version check using GS2-Version at login or session reconnection. If an error occurs as a result of the version check, the event handler registered with Gs2AccountAuthenticator::onDetectVersionUp will be called. Argument name Type Description versionNamespaceName string GS2-Version namespace name (if omitted, no version check is performed) targetVersions EzTargetVersion[] game version information Implementation example","lang":"en","section":"api_reference","summary":"how to initialize GS2-SDK for Game Engine","title":"Game Engine","url":"/api_reference/initialize/game_engine/"},{"content":"What is Transaction Processing? Transaction processing in GS2 refers to the mass execution of exchanging resources defined as “consume action” and “get action”. APIs that issue transactions are such as GS2-Exchange’s exchange execution function (Exchange), GS2-Showcase’s product purchase function (Buy), and GS2-Quest’s quest start function (Start). Consumption actions\" are user data operations that are disadvantageous to the player, while “acquisition actions” are user data operations that are beneficial to the player. In GS2-Inventory, the consumption of an item is a “Consume Action” and the acquisition of an item is an “Acquire Action”. For a slightly different example, in GS2-Inbox, setting the open flag on a message is a “consume action” and receiving an item attached to a message is an “acquire action. Understand that in GS2, the game cycle is achieved by repeatedly issuing and executing transactions that rewrite user data. Transactions and Stamp Sheets In GS2, transaction processing was called a “stamp sheet. As a result, you will find such descriptions throughout the code and documentation. In recent years, this name is no longer actively used and is referred to as “transaction processing,” but it should be understood to refer to the same thing. A similar term is “stamp task,” which refers to a “consumption action” contained within a transaction. Transaction Execution When you call Exchange in GS2-Exchange or Buy in GS2-Showcase, an object called EzTransactionDomain is returned. EzTransactionDomain has a Wait function, which can be called to wait for the transaction to complete. However, it is strongly recommended to implement a timeout since there is no guarantee of the amount of time it will take for transaction processing to complete. The Wait function has an argument called all, which can be set to true to wait for the completion of the transaction if a new transaction is issued within the transaction processing. If the Wait function is not called, Gs2Domain::Dispatch must be called periodically. Deep Dive The rest of this section describes the detailed implementation of transaction processing. Most developers do not need to understand what is written below. The order in which the consume and acquire actions are executed The order of execution is controlled so that the “get action” can be executed after all the “consume actions” included in the transaction have been executed. Therefore, the order of execution is “consume action” first and “acquire action” second. This is an important specification to achieve cheat tolerance. This process flow is compared to the “approval process” in which a Japanese company makes a decision, Ask the various executives (microservices) for permission (to perform the consumption action) and have them put their stamp on the request for approval, We called it a stamp sheet because when you get permission from all the microservices, you can execute what you really wanted to do (obtain action). Execute transaction The microservices provided by GS2 have the ability to execute a process by passing the “consume action” or “obtain action” contained in a transaction. However, it is difficult to determine which action contained in a transaction should be passed to which API of which microservice, depending on the type of action, and executing it can be a challenge. This is where GS2-Distributor microservice comes into play. When GS2-Distributor receives a transactional action, it has a process that forwards it to the appropriate microservice API depending on the content of the action. This allows you to simply pass transaction data to GS2-Distributor and execute the transaction without having to think about it. Error Handling The next thing to consider is error handling; GS2 provides a variety of microservices, and when a failure occurs, it may occur on a per-microservice basis. In other words, there could be a case where the “consume action” is successfully executed, but the “get action” fails. In this case, the “get action” is not executed successfully until the “consume action” succeeds. In this case, if the player does not retry until the “get action” succeeds, the process will stop with the player losing money. Automatic Execution of Transaction Processing In the past, GS2 left error handling to the game developer. However, since it is not appropriate to leave error handling, which is not highly productive, to many GS2 users, the “automatic transaction execution” function was developed to ensure that GS2 takes care of this responsibility. The “TransactionSetting” item is always included in the namespace settings of microservices that have the ability to issue transactions. In the “TransactionSetting” section, there is a flag called “EnableAutoRun” to enable auto-execution, which is now enabled by default in the configuration using the management console. With transaction auto-execution enabled, when calling an API that issues a transaction, such as GS2-Showcase’s Buy, the API will respond only with the transaction ID and not the transaction payload. Instead, data is handed off internally to GS2-Distributor to execute the transaction. The GS2-Distributor then executes the received transaction and retries if an error occurs. Because it operates through this mechanism, processing is usually completed within one second, but there is no guarantee as to how long it will take to complete transaction processing, as retries may occur if an error occurs. Waiting for auto-executed transactions to complete and retrieve results When auto-execution of a transaction is enabled, it is unclear whether the transaction is completed or uncompleted as it is. GS2-Distributor therefore has a mechanism to send a notification to the game when the transaction auto-execution is complete. To use this functionality, the GS2-Distributor must be configured with a GS2-Gateway namespace to issue notifications to, and games must be configured with a user ID to receive notifications for the GS2-Gateway namespace. Projects created after August 2023 will automatically create a GS2-Distributor or GS2-Gateway named default, and will use this namespace for these processes if not specifically configured in the SDK. The content of the notification includes a “transaction ID”, and GS2-Distributor provides an API to retrieve the results of the transaction execution by specifying the “transaction ID”. Executing multiple get actions As explained above, multiple “consume actions” can be set, but only one “acquire action” can be set. This is due to the cheat-resistant backstop of the transaction, which states that the get action can be executed after all spend actions have been executed. On top of this mechanism, it means that having multiple acquisition actions would complicate things in many ways. However, it is conceivable in various cases that there are multiple acquisition actions to increase or decrease resources in the game. This is where the GS2-JobQueue microservice comes in. GS2-JobQueue provides a mechanism for delayed execution of “acquisition actions. GS2-JobQueue can register up to 10 jobs in a single API call. There is a get action called “register job to GS2-JobQueue,” and if multiple get actions are set, they are internally converted to this get action when a transaction is issued. If the number of acquisition actions exceeds 10, it is converted to “register job to GS2-JobQueue” and up to 100 acquisition actions can be included in a single transaction. Projects created after August 2023 will now create a GS2-JobQueue named “default” and use this namespace for processing. You can use any queue by specifying the namespace ID in JobQueueNamespaceId in “TransactionSetting,” but there is no need to do so unless there is a special reason. Executing GS2-JobQueue GS2-JobQueue execution has the same past as transactions. Execution of jobs registered with GS2-JobQueue also required explicitly calling the execution API for jobs registered with GS2-JobQueue. The job was removed from the job queue upon successful execution, and since the return value of the job’s execution API included in the response value whether the job queue was empty, it was left to the game developer’s responsibility to have the process rotate until it was empty. If a job failed to execute, the job was not removed from the job queue, so retries could be easily implemented by repeatedly running the job until the queue was empty. GS2-JobQueue auto-execution However, since it is not appropriate to leave this unproductive process to many GS2 users, the “automatic job execution” function was designed to ensure that GS2 would take care of this responsibility. The GS2-JobQueue namespace configuration provides an auto-execute flag for the job queue, which is now enabled by default. As with transactions, when auto-execution is enabled, processing begins automatically when a job is queued, and when execution is complete, GS2-JobQueue notifies the GS2-Gateway set in the GS2-JobQueue namespace of the “completed job ID”. GS2-JobQueue can specify a “job ID” to obtain the results of job execution. Projects created after August 2023 will automatically create a GS2-Gateway named default, and will use this namespace for these processes if not specifically configured in the SDK. Who is EzTransactionDomain::Wait Now, I have explained the internal processing at length. Finally, let’s consider again what EzTransactionDomain’s Wait does. When GS2-Showcase::Buy is called, a transaction is issued, and if auto-execution is enabled, it waits for a completion notification of the transaction ID issued by GS2-Gateway. If auto-execution is disabled, the returned transaction data is passed to GS2-Distributor for execution. If auto-execution is enabled, the transaction execution result is retrieved from GS2-Distributor; if not auto-execution, the result of explicitly calling GS2-Distributor is used to retrieve the transaction execution result. If there was a transaction issue process involved, it creates a new EzTransactionDomain and calls its EzTransactionDomain::Wait if all is true. If the “get action” of the executed transaction was a job registration to GS2-JobQueue, there is additional processing. If auto-execution of GS2-JobQueue was enabled, it waits for the execution completion notification of the registered job ID from GS2-Gateway; if auto-execution was disabled, it explicitly executes the job in GS2-JobQueue. If the job execution result includes transaction issuance processing or job registration to GS2-JobQueue, it also waits for those processes to complete if all is true. Who is Gs2Domain::Dispatch? When GS2-Distributor’s transaction execution or GS2-JobQueue’s job execution completion notification is received from GS2-Gateway, the SDK’s local cache is rewritten according to the result of the processing. This makes it possible to retrieve the latest value without calling the API for retrieving the quantity of items in the possession of an item as a result of a change in the quantity of items in the possession of an item due to transaction processing. Since Gs2Domain::Dispatch is called in EzTransactionDomain::Wait when waiting for notification from GS2-Gateway, it is not necessary to explicitly call Gs2Domain::Dispatch when using Wait. However, if you do not call EzTransactionDomain::Wait or if you specify false for the all argument, you must call Gs2Domain::Dispatch otherwise the cache will not reflect the results of execution by transactions or job queues. Example of implementation to wait for transaction completion and obtain processing results EzTransactionDomain This retains information about transactions that have been executed using the server-side automatic transaction execution function. Result Type Description transactionId string Transaction ID jobName string Name of the job executed in JobQueue TransactionSetting Details The details of the transaction settings are as follows. Type Activation Conditions Description enableAutoRun bool Whether to automatically execute the issued transaction on the server side. enableAtomicCommit bool When enableAutoRun is enabled Whether to commit the transaction execution atomically. transactionUseDistributor bool When enableAtomicCommit is enabled Execute the transaction asynchronously using GS2-Distributor acquireActionUseJobQueue bool When enableAtomicCommit is enabled Use GS2-JobQueue when executing an acquisition action This is used when there are multiple acquisition actions that operate on the same resource.","lang":"en","section":"api_reference","summary":"Transaction Processing in GS2-SDK for Game Engine","title":"Game Engine","url":"/api_reference/transaction/game_engine/"},{"content":"GS2 Sample Project for Unity This is a sample implementation of the following functions as they would work in a game. Credential (authentication information) Login App version check Terms of Use Confirmation Account linking/transfer Notifications Stamina/Stamina Store Billing Currency / Billing Currency Store Gold Inventory Quests Lottery Function Chat Friends Matchmaking Real-time matchmaking","lang":"en","section":"articles","summary":"Introduction of GS2 Implementation Samples\n","title":"GS2 implementation samples","url":"/articles/sample/project/"},{"content":"This section summarizes the configuration steps in the GS2 management console that are required to create a Unity / Unreal Engine 5 project and take advantage of GS2’s features. Create a GS2 account First, register for a GS2 developer account at GS2’s website . After registration, you will receive an e-mail confirming your e-mail address. After accessing the URL in the email and verifying your email address, login to the Management Console with your registered account information. Create a project Next, create a project in the Management Console . A project is paired with a development game title. GS2 resources (configured contents, master data, etc.) are maintained for each project. They cannot interfere with the resources of other projects. You can create a project either when you start creating a new game title or in the middle of development. log in to the Management Console . Open the Project \u003e Project List page. Click on Create New Project . Enter the Project Name and Description and click the Create button. Only upper and lower case alphanumeric characters, hyphens and underscores are allowed in the project name. Example: MySuperCool_Stg_Game-001 .","lang":"en","section":"get_start","summary":"Register with GS2 and create a project\n","title":"GS2 setup","url":"/get_start/tutorial/setup_gs2/"},{"content":"This is a sample implementation of GS2 UIKit for Unity functionality. GS2 UIKit is a library for building game UIs with no code, enabling you to efficiently build UIs for various screen configurations. This section describes a publicly available sample project in great detail. By using UIKit to build UIs with no code, it should be possible to significantly reduce the implementation costs incurred by programmers. Common resources throughout UIKit https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Core/initialize_core_template.yaml Template for creating common resources needed for the sample to work. Setting up credentials https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Core/DevEnvironment.asset Scriptable Object to set the GS2 credentials used by the UI Kit. Credentials for the environment prepared by GS2 are set to facilitate checking the operation. Credentials are changed irregularly, so if your samples stop working, please update them to HEAD in the repository. We recommend that you use the credentials of your own environment when checking the detailed behavior.","lang":"en","section":"articles","summary":"Introduction of GS2 UIKit for Unity implementation samples","title":"Sample implementation of GS2 UIKit for Unity","url":"/articles/sample/uikit_project/"},{"content":"The account system provided by Game Server Services is an “anonymous account” type of account system. This is a major system in Japan, but may be unfamiliar in other regions. However, this account system makes a lot of sense for games. What is an anonymous account? When you think of account management, you usually think of having a login ID and a password. Anonymous accounts are no different. However, the most important feature is that both the login ID and password are randomly generated by the system. The login ID and password issued by the system can be saved to the local storage of the device, and the game can be resumed by logging in with this information for the second and subsequent times. graph TD Startup --\u003e LoadSave{\"Load Anonymouse Account from Device Storage\"} LoadSave -- Not Exists --\u003e CreateAccount[\"Create Anonymouse Account\"] CreateAccount --\u003e SaveAccount[\"Save Anonymouse Account\"] SaveAccount --\u003e Login LoadSave -- Exists --\u003e Login Login --\u003e InGame Advantages of Anonymous Account Easy registration: Users can start playing games immediately without going through a complicated registration process. Especially in free-to-play (F2P) style games, reducing the registration process is important for encouraging more users to try the game. Protection of player information: Since users do not need to set their own login IDs or passwords, personal information and privacy are protected. In addition, there is no need to reset or change passwords. Easy transfer of game data: Users can use various platform IDs or social media accounts as transfer information, making it easy to transfer data between different devices or applications. Anonymous gameplay experience: Players can enjoy a more free gameplay experience by playing games anonymously without using their real names or nicknames. TakeOver No other place is as unreliable as your device’s local storage. You could drop your device or destroy it. If you lose all your game data, you are in a no-win situation. Players can experience the game with an anonymous account, and if they really like it, they can register “Takeover Information”. You can use information from various game publishers’ ID bases for the Takeover Information, or you can set up a social networking account. Game publishers’ ID bases can also be a good choice. The Takeover Information will include user IDs and other information obtained as a result of authentication with the various ID platforms. Then perform the takeover on an entirely new device. Log in to the various ID platforms and perform the takeover using the user ID you received. Information can be obtained to log in with an anonymous account created in the past with the Takeover Information. This information is stored in the local storage of the device and will be used for future logins. graph TD InGame -- Loved the game very much! --\u003e AddTakeOverSetting[\"Add Takeover Information\"] AddTakeOverSetting --\u003e BrokenDevice[\"Broken Device\"] NewDevice[\"New Device\"] --\u003e DoTakeOver[\"Execute TakeOver (Enter Takeover Information)\"] DoTakeOver -- Restore Anonymouse Account --\u003e SaveAccount[\"Save Anonymouse Account\"] SaveAccount --\u003e Login OpenID Connect Connectivity Support is available to use OpenID Connect compliant authentication systems for registering takeover information and executing the takeover process. Registering Authentication Services To use the OpenID Connect integration feature, master data configuration is required. You can specify the integration destination for each transfer slot, supporting up to 1,025 different authentication methods. The configuration items are as follows: OpenID Connect Discovery Endpoint URL Authentication service client ID Authentication service client secret Redirect URL after authentication completion Additional scope values to request Additional return values to obtain from the authentication result Sign in with Apple must calculate the client secret dynamically, but it also provides this calculation functionality. If you specify a Sign in with Apple URL in the Spec URL based on OpenID Connect Discovery, then instead of the client secret, the Apple Developer team ID ID of the private key issued by Apple Payload (PEM) of the private key issued by Apple The client secret is calculated by GS2 as needed. Authentication Process GS2 also provides support for authentication processing. An API for obtaining the URL of the authentication page of an authentication service and a callback handling endpoint after authentication from the authentication service are provided. The callback URL for the authentication service should be set to a value according to the following format https://account.{region}.gen2.gs2io.com/{ownerId}/{namespaceName}/type/{type}/callback https://account.ap-northeast-1.gen2.gs2io.com/aAbBcCdD-project/namespace-0001/type/0/callback Upon receiving the authentication callback, the user will be redirected to the following URL https://account.{region}.gen2.gs2io.com/{ownerId}/{namespaceName}/type/{type}/done?id_token={idToken} The ID token obtained by authenticating to the URL query string is passed across. Using non-GS2 authenticators such as Firebase Authentication Once the ID token is obtained, the method does not have to be the above procedure. Deny registration from non-Authentication services Slots with OpenID Connect integration in the master data will not be able to register transfer information using any user identifier and password, nor will they be able to perform transfers. Example Implementation Creating an Anonymous Account GS2-Account has a hierarchy of namespaces that allows multiple pools of accounts within a single project. There is no specific purpose for namespaces, and they can be used as needed, for example to separate namespaces for different deployment regions. Logging in using an anonymous account The GS2-Account authentication process must be redone at regular intervals. Here is an example of a login using Gs2AccountAuthenticator, a utility class that automatically performs such processing. By specifying Gs2AccountAuthenticator and the user ID and password of the anonymous account you created to the GS2 API client, you can obtain a GameSession instance that represents the session information during login. From now on, this GameSession instance will be used to access the information of the logged-in player. Special Exceptions During Authentication The following special exceptions may occur during authentication processing: Exception Type Base Type Description PasswordIncorrectException UnauthorizedException Password does not match BannedInfinityException UnauthorizedException Account has been suspended It is recommended that the game properly handles these exceptions and displays appropriate error messages to the user. How these exceptions are surfaced when logging in via Gs2AccountAuthenticator / FGs2AccountAuthenticator depends on the SDK wrapper implementation. See the API Reference for details. Registering takeover setting You can maintain multiple takeover settings for an account by specifying different values for the slot number. Slot numbers range from 0 to 1024, allowing up to 1,025 takeover settings per account. For example, you can store an email address/password in Slot Number:0 and social media ID information in Slot Number:1, allowing players to choose their preferred takeover method. Password Handling in Takeover Settings The password registered in takeover information is hashed and stored on the server side. Once a password is set, it cannot be retrieved via API. If forgotten, a new takeover setting must be issued. This mechanism ensures secure retention of player authentication information while preventing unauthorized use. Get list of registered takeover setting Perform takeover OpenID Connect Authentication Process The following sample uses unity-webview for the in-app browser. public static async UniTask OpenAuthentication( WebViewObject webView, Gs2Domain gs2, string namespaceName, IGameSession gameSession, int type ) { string idToken = null; webView.Init( separated: true, ld: url =\u003e { if (new Uri(url).LocalPath.EndsWith(\"/done\")) { var codeField = new Uri(url).Query.Replace(\"?\", \"\").Split(\"\u0026\").Select(v =\u003e new KeyValuePair (v[..v.IndexOf(\"=\", StringComparison.Ordinal)], v[(v.IndexOf(\"=\", StringComparison.Ordinal)+1)..])).FirstOrDefault(v =\u003e v.Key == \"id_token\"); idToken = Uri.UnescapeDataString(codeField.Value); webView.SetVisibility(false); } } ); webView.LoadURL( (await gs2.Account.Namespace( namespaceName ).Me( gameSession ).GetAuthorizationUrlAsync( type )).AuthorizationUrl ); webView.SetInteractionEnabled(true); webView.SetVisibility(true); await UniTask.WaitWhile(() =\u003e idToken == null); return idToken; } Registering takeover information using OpenID Connect Executing a takeover using OpenID Connect Other functions Platform ID management GS2-Account can store user IDs used on platforms such as X and Instagram. Other players can search for these IDs and invite friends from social networks. Platform IDs are managed in slot numbers 0–1024, and multiple IDs can be registered per account. Registering a Platform ID Searching Users by Platform ID Listing Registered Platform IDs Custom script triggers Event triggers can invoke GS2-Script before and after processing such as account creation, authentication, handovers, and bans. Triggers support synchronous or asynchronous execution; asynchronous processing can integrate with GS2-Script or Amazon EventBridge. Main event triggers and script setting names are: createAccountScript (completion notification: createAccountDone ): before and after account creation authenticationScript (completion notification: authenticationDone ): before and after login createTakeOverScript (completion notification: createTakeOverDone ): before and after registering takeover information doTakeOverScript (completion notification: doTakeOverDone ): before and after executing a takeover banScript (completion notification: banDone ): before and after applying a ban unBanScript (completion notification: unBanDone ): before and after lifting a ban Automatic Password Change Namespace settings allow for automatically changing the password when performing a takeover. By using this feature, you can prevent logging in from the previous device after a takeover is executed. However, this feature does not completely prevent simultaneous logins from multiple devices. GS2-Gateway provides functionality to reject simultaneous logins by the same user, which offers more robust protection against concurrent logins. User Data Anonymization When differentUserIdForLoginAndDataRetention is enabled in the Namespace settings, separate User IDs for login and Data Owner IDs for data retention are issued. Applications continue to use the User ID for authentication, while server-side user data uses the Data Owner ID, enabling separation between personal information and in-game data. This feature allows data analysis to be performed on anonymized user data, achieving both privacy protection and operational data collection. Master data management Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: TakeOverTypeModel : takeover settings and OpenID Connect information for each slot number Below is a JSON example of master data that configures an OpenID Connect integration: { \"version\": \"2024-07-30\", \"takeOverTypeModels\": [ { \"type\": 0, \"metadata\": \"Google\", \"openIdConnectSetting\": { \"configurationPath\": \"https://accounts.google.com/.well-known/openid-configuration\", \"clientId\": \"your-client-id\", \"clientSecret\": \"your-client-secret\" } } ] } For Sign in with Apple, specify appleTeamId / appleKeyId / applePrivateKeyPem instead of clientSecret . See Registering Authentication Services for details. Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Setting per-player time offsets Game Server Services account information can have a time offset. This offset can be set to how many minutes into the future the player will behave as a state. This feature can be used to let QA staff play the game in a state one hour into the future, even within the production environment. This way, problems such as an event not being opened when it is time to start the event can be quickly noticed. Account Suspension It is possible to suspend a player for bad behavior in the game. Ban states are recorded as multiple BanStatus entries containing reasons and planned release times, and the account retains a flag indicating whether it is banned. Event triggers can be configured before and after adding or removing bans to coordinate with external systems. Detailed Reference Reference of GS2-Account","lang":"en","section":"microservices","summary":"Account management feature\n","title":"GS2-Account","url":"/microservices/account/"},{"content":"It has become common practice to have players view ads and earn rewards from ad platforms as a monetization method for mobile games. When an ad is viewed correctly, the ad platform notifies GS2 via server-to-server coordination, and rewards are granted by GS2, thereby preventing cheating. In designs where rewards are granted solely via client-side callbacks, there is a risk of cheating using a tampered SDK. GS2-AdReward provides a mechanism that issues rewards based on trusted viewing-completion events delivered via direct Server-to-Server (S2S) notifications from the ad platform to GS2. Ad Viewing Point In general, GS2 exchanges resources by setting compensation and rewards, but since the specifications for server-to-server communication differ among advertising platforms and the granularity of data also differs, GS2-AdReward adds one “Ad Viewing Point” when an ad is confirmed as viewed. The “Ad Viewing Point” earned can be consumed as a consume action that can be used in GS2-Exchange, GS2-Showcase, and other services. This loosely couples ad viewing with any in-game reward, so the reward design can be reused when adding new ad campaigns. Transaction Actions GS2-AdReward provides the following transaction actions: Type Action Description Consume Gs2AdReward:ConsumePointByUserId Consume viewing points Acquire Gs2AdReward:AcquirePointByUserId Add viewing points graph TD InGame[\"Game\"] -- view Ad --\u003e ViewAd[\"Ad\"] ViewAd -- Ad has been viewed --\u003e AdPlatform2[\"Ad Platform\"] ViewAd -- Ad has been viewed --\u003e InGame2[\"Game\"] AdPlatform2 -- Notification that ad has been viewed --\u003e AdReward[\"GS2-AdReward\"] AdReward --\u003e AddPoint[\"Give Points\"] AdReward -- Notify that points have been awarded --\u003e InGame2 InGame2 -- Exchange viewing points for items --\u003e Exchange[\"GS2-Exchange\"] Supported Advertising Platforms GS2-AdReward currently supports the following advertising platforms. Please contact support if you would like additional platforms to be supported. Platform Callback Identifier AdMob (Google Mobile Ads) admob Unity Ads unityad AppLovin MAX applovinmax AdMob Settings You need to enable “Server Side Verification” in the Ad Unit settings and set the URL issued by GS2. Please refer to the following for the setup procedure. https://support.google.com/admob/answer/9603226 Configure the namespace settings with the ad unit IDs to be rewarded ( allowAdUnitIds ). Callbacks from ad units not registered here are ignored, preventing unauthorized issuance of viewing points from unexpected ad units. Example of Callback URL https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/admob Unity Ads Settings Specify the Game ID issued by Unity Ads and the URL issued by GS2 to have the private key issued. See below for the setup procedure. https://docs.unity.com/ads/en-us/manual/ImplementingS2SRedeemCallbacks Set the private key ( keys ) in the namespace configuration. Multiple keys can be registered when supporting multiple games. Example of callback URL https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/unityad AppLovin MAX Configuration By adding AppLovin MAX configuration ( appLovinMaxes ) to the Namespace, points can be awarded from the view completion WebHook. Field Description allowAdUnitId Allowed ad unit ID. The adUnitId included in the callback is verified against this value, blocking unauthorized requests. eventKey The event key issued in the AppLovin MAX management console. Used to verify that the WebHook was sent from an authorized source. Example callback URL: https://ad-reward.{region}.gen2.gs2io.com/callback/{ownerId}/{namespaceName}/applovinmax Push Notifications The main push notifications that can be configured and their setting names are as follows: changePointNotification : Notification when points change due to ad viewing Because the result is not delivered directly to the client until the viewing completion notification arrives from the ad platform via server-to-server coordination (S2S), it is important to inform the client that “points have been granted” through push notifications. Implementation Example Start watching videos You can directly use the SDK of each advertising platform to watch videos. The implementation example here shows an example using the utility classes provided by GS2-SDK. With the utility class, you can automatically wait from viewing completion until the arrival of changePointNotification , allowing simple “waiting for point award” handling on the UI side. AdMob Unity Ads AppLovin MAX Get current ad points Viewing point accrual callback When viewing points are increased by an S2S notification from the ad platform, a notification is delivered to the client via changePointNotification . By subscribing to this callback, you can implement UI updates or effects immediately after viewing completion. Other Features Resetting points User-held viewing points can be reset (deleted) via the management console or API. This is useful for switching campaigns or for operational adjustments. Viewing History Viewing completion notifications received from ad platforms are retained as History . This ensures idempotency by preventing points from being granted twice when a notification with the same transactionId is resent. Custom Script Triggers Event triggers can be configured to invoke GS2-Script before and after point processing. These can be utilized for game-specific validation or auditing. Triggers support both synchronous and asynchronous execution, with asynchronous processing enabling external integration through GS2-Script or Amazon EventBridge. Main event triggers and script setting names are: acquirePointScript (completion notification: acquirePointDone ): before and after adding points from ad viewing consumePointScript (completion notification: consumePointDone ): before and after consuming viewing points for item exchanges, etc. Asynchronous triggers can route through Amazon EventBridge to forward data to external systems for view-count aggregation, BI tool integration, and the like. Detailed Reference Reference of GS2-AdReward","lang":"en","section":"microservices","summary":"Ad reward feature","title":"GS2-AdReward","url":"/microservices/ad_reward/"},{"content":"GS2-Buff provides a centralized function to manage compensation and rewards for microservices provided by GS2, as well as corrections to the maximum value of user data. It can be used to realize features such as increasing rewards for a limited period of time or raising the maximum value of user data while a subscription is active. Rather than directly rewriting other microservices, GS2-Buff propagates correction values to each microservice via meta information called a “context stack” passed in API calls. A major characteristic is therefore that buffs can be applied or removed without rewriting the master data or player data of any microservice when the buff content or duration is changed. Use cases Typical use cases for GS2-Buff are as follows: A limited-time campaign that doubles the amount of experience gained A flat 20% discount on items sold in a specific showcase Raising the maximum stamina value while a subscription is active Increasing quest rewards only while a specific piece of equipment is equipped Halving the consumption of enhancement materials during an event period graph LR Player[\"Player\"] --\u003e|ApplyBuff| Buff[GS2-Buff] Buff --\u003e|Context Stack| Player Player --\u003e|API + Context Stack| Other[\"Other Microservices (GS2-Experience / GS2-Stamina / GS2-Showcase, etc.)\"] Other -.reference.-\u003e Buff Other --\u003e|Corrected values| Player Master Data Management Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: BuffEntryModel : Basic model that defines the correction value and its targets Master data can be registered through the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Main configuration items of BuffEntryModel Setting Description name Unique name identifying the buff metadata Arbitrary metadata for client-side use expression Type of correction calculation ( Rate Add / Mul / Value Add ) targetType Whether the correction target is a “model” or an “action” targetModel / targetAction Target model/action name, condition GRN, and correction rate priority Application priority. Calculated in order from the smallest value applyPeriodScheduleEventId Validity period defined by a GS2-Schedule event Buff entity The unit of correction applied to each microservice. Defines the degree of increase or decrease for each parameter, with the base value set to 1.0. The main types of buffs available and their calculation methods are as follows: Rate Add : Adds to the correction rate Mul : Multiplies the correction rate Value Add : Directly adds to the value (only for model or action values) Rate Add and Mul perform operations on the correction rate. For example, Rate Add 1.5 makes the correction value 2.5x, while Mul 1.5 makes it 1.5x. Value Add directly adds to the value; Value Add 5 results in a correction of +5. Application priority The correction value can be set with an application priority. Correction values are calculated in order starting from the one with the smallest priority value. For example, suppose the following correction values are defined: Correction value type Correction value Application priority Rate Add 0.2 1 Mul 1.5 2 Rate Add 0.2 3 In this case, the calculation is performed in the following order: 1.0 + 0.2 = 1.2 1.2 * 1.5 = 1.8 1.8 + 0.2 = 2.0 The final correction value is then 2.0x. Correction calculations involving Value Add If a correction value contains a “Value Add”, the correction calculation is calculated once before the priority at which the “Value Add” is defined, and then the value is added to the calculated value. Correction Value Type Correction Value Application Priority Rate Add 0.2 1 Mul 1.5 2 Value Add 2 3 Rate Add 0.2 4 In this case, the calculation of correction values up to just before the appearance of Value Add is performed first. 1.0 + 0.2 = 1.2 1.2 * 1.5 = 1.8 This correction value is then applied once to the input value. For example, if the input is 10, multiplying by 1.8 gives a corrected value of 18. The “Value Add” of +2 is then applied to the corrected value, resulting in a corrected value of 20. Next, the calculation of the correction value from immediately after the appearance of Value Add is performed. 1.0 + 0.2 = 1.2 This correction value is then applied once to the input value. If the input is 10, multiplying by 1.2 gives a corrected value of 12. This value is added to the corrected value after “Value Add”. 20 + 12 = 32 Thus the final corrected value for an input of 10 is 32. The entire equation can be summarized as follows, where the input value is x: ((x * (1.0 + 0.2) * 1.5) + 2) + x * (1.0 + 0.2) Setting correction targets There are two main types of buff correction targets: “models” and “actions”. Please refer to the documentation on buffs for each microservice to find out what models and actions can be set. Models Examples of models that can be applied include: GS2-Experience rank cap GS2-Stamina stamina maximum value GS2-Showcase acquire action GS2-Showcase consume action Actions Examples of actions that can be applied include: GS2-Experience amount of experience gained GS2-Stamina stamina recovery amount GS2-Stamina stamina consumption amount Setting the conditions for applying the correction If applied to GS2-Showcase, to which DisplayItem is the correction value applied? If applied to GS2-Experience, to which Status should the correction value be applied? This parameter is used to set such application conditions. Please refer to the documentation for each microservice’s buff to find out what application conditions can be set for each buff. Models and GRNs Specify the model and GRN as the application condition. Some buffs allow multiple models to be specified. For example, for GS2-Showcase, there is a pattern that specifies the GRN of the Showcase in order to apply the correction to all DisplayItems in the Showcase, and a pattern that specifies the GRN of a DisplayItem to apply the correction only to a specific DisplayItem in the Showcase. Multiple application conditions can be set for a buff, and if any of the conditions is met, the correction value is applied. In other words, by setting multiple DisplayItems as application conditions for one buff entity, a single buff entity can define correction values for multiple DisplayItems. How to apply corrections Calling GS2-Buff’s ApplyBuff API returns a “context stack” response. Every API provided by GS2 has an interface that allows a context stack to be specified. By specifying the context stack returned by GS2-Buff in each API call, the buff can be applied. In some high-level SDKs, such as those for game engines, the context stack is wrapped and does not need to be explicitly specified. sequenceDiagram participant Player as Player participant Buff as GS2-Buff participant Other as Other Microservice Player-\u003e\u003eBuff: ApplyBuff Buff--\u003e\u003ePlayer: Context Stack Player-\u003e\u003eOther: API call (with Context Stack) Other--\u003e\u003ePlayer: Buff-applied value Scope of application of buffs The scope of buff application is broad, and buffs are also applied in master data acquisition APIs. If a master data acquisition API is called with the context stack specified, the buffed value is returned. If you want to display the value of the unbuffed state alongside it in the game, you need to combine API calls that do not include the context stack. Linking buff entities to GS2-Schedule Buff information in the context stack retains its validity period. This means that if a buff entity has a GS2-Schedule event set as its validity period, the buff will automatically stop being applied once outside the event period. However, if the buff application conditions are changed or a new buff is added, you need to call ApplyBuff again to reflect the buffs. Expiry date of context stacks Context stacks have an expiry date. After 24 hours from the time ApplyBuff is called, the context stack loses its effect. ApplyBuff should be executed again within 24 hours even if the conditions have not changed. Overriding rates from scripts By returning OverrideBuffRate (a pair of name and rate ) as the return value of the synchronous applyBuffScript , you can dynamically override the rate of the corresponding buff at the time of application. This is useful when you want to vary buff rates finely according to player state, time of day, or equipped gear. Script Triggers Event triggers can invoke GS2-Script before and after buff application. Triggers support synchronous or asynchronous execution, and completion notifications can be delivered via doneTriggerTargetType , such as to Amazon EventBridge. Main event triggers and script setting names are: applyBuffScript (completion notification: applyDone ): before and after applying a buff. The buff rate can also be dynamically overridden via the script’s return value. Example implementation Apply a buff When ApplyBuff is called, the Gs2 object itself is switched to a new instance that holds the post-buff context. By using the returned Gs2 object for subsequent access, you can use each microservice with the buff applied. Get a list of registered buff entities You can retrieve the currently registered buff entities for purposes such as displaying a list of in-game campaigns. Get a specific buff entity Combining with other microservices GS2-Buff is used in combination with other microservices rather than on its own. Examples of major integrations and corresponding correction targets are as follows: Integration Examples of correction targets GS2-Experience Experience gain amount, rank cap GS2-Stamina Stamina maximum value, recovery amount, consumption amount GS2-Showcase DisplayItem sale price, acquired quantity GS2-Money2 Deposit amount, consumption amount GS2-Inventory Item acquired quantity GS2-Quest Quest reward acquired quantity GS2-Enhance Number of enhancement materials consumed For details on which model and action names each microservice accepts buffs for, please refer to the documentation of that microservice. Detailed Reference Reference of GS2-Buff","lang":"en","section":"microservices","summary":"Buff feature","title":"GS2-Buff","url":"/microservices/buff/"},{"content":"GS2-Chat allows you to add text chat to your game. Text chat requires an always-on session to detect new messages and has complex server requirements. Game Server Services frees you from the hassle of managing these always-on sessions. Room To start using GS2-Chat, you must first create a room. Rooms can be created freely by the player, or you can have a room created for you by the developer. You can also set a whitelist of user IDs that are allowed to post, enabling you to build rooms exclusive to specific members. One thing to keep in mind is that GS2-Chat only guarantees a maximum of 3 messages per second per room. Posting more than this may cause errors. Therefore, it is not suitable for requirements such as social networking timelines where a large number of players are stored in a single room. Passwords Rooms can be assigned a password. The password must be specified when retrieving messages from a password-protected room or when posting a message. Updating Room Settings After a room is created, it is possible to update the metadata, password, and whitelist (list of user IDs allowed to post). This allows you to dynamically change room access permissions and room attribute information. Subscription Players can subscribe to a room to receive notifications of new messages in the room. Messages can be categorized, and subscriptions can be made for each category in the room. In a guild chat implementation, only messages from the guild master can be set to a special category, so that guild members can be sure to subscribe only to messages from the guild master. Subscription settings can also be updated later. You can dynamically add or remove categories to receive, and change the mobile push notification transfer settings when offline. Notification by subscription is handled by the GS2-Gateway’s notification functionality, but the GS2-Gateway does not have the ability to subscribe to messages when the player being notified is offline. The GS2-Gateway does provide a feature for out-of-game notifications, such as mobile push notifications. There is no explicit limit on the number of people who can subscribe to a room, but GS2-Gateway API requests are required to send notifications, so the GS2-Gateway API usage fee is charged per notification. Also, the more notifications you have, the longer it will take for the notifications to reach you. It is also possible to specify a room name and get a list of who is currently subscribing to that room. actor Player1 actor Player2 participant \"GS2-Chat#Room\" participant \"GS2-Gateway#Namespace\" participant \"Firebase Cloud Messaging\" Player1 -\u003e \"GS2-Chat#Room\" : Subscribe Player2 -\u003e \"GS2-Chat#Room\" : Post Message \"GS2-Chat#Room\" -\u003e \"GS2-Gateway#Namespace\" : Send Notification to Player1 \"GS2-Gateway#Namespace\" -\u003e \"Firebase Cloud Messaging\" : Notification(if player is offline) \"GS2-Gateway#Namespace\" -\u003e Player1 : Notification Player1 -\u003e \"GS2-Chat#Room\" : Load New Message Messages You can send messages to a room. The message retention period can be specified in the namespace setting messageLifeTimeDays in the range of 1 to 30 days; messages older than the retention period are deleted. A feature is also available to retrieve a certain number of the latest messages. This allows efficient display of past logs immediately after entering a room. NG Words The message payload may contain inappropriate words. By working with GS2-Script, you can refuse to post messages that contain inappropriate words or rewrite the message payload. Because GS2-Script can output HTTP communications, it can also forward them to its own NG word check server for processing. actor Player participant \"GS2-Chat#Room\" participant \"GS2-Script#Script\" Player -\u003e \"GS2-Chat#Room\" : Post Message \"GS2-Chat#Room\" -\u003e \"GS2-Script#Script\" : Trigger post message \"GS2-Script#Script\" -\u003e \"GS2-Chat#Room\" : Continue? / Replaced Message Category Model and Notification Settings Message categories can be defined in master data. For each category, you can configure whether to reject posts using access tokens or forward them to mobile push notifications when offline. Transaction Actions GS2-Chat does not provide transaction actions. It is possible to call other microservice APIs from the message-posting script trigger to rewrite user data in response to specific message posts. Script Triggers GS2-Script can be invoked before and after each of the following actions: room creation/deletion, message posting, and subscription/unsubscription. You can use synchronous execution for validation or tampering checks, or asynchronous execution to integrate external systems via Amazon EventBridge. The main configurable event triggers and corresponding script names are as follows: createRoomScript (Completion notification: createRoomDone ): Before and after room creation deleteRoomScript (Completion notification: deleteRoomDone ): Before and after room deletion postMessageScript (Completion notification: postMessageDone ): Before and after message posting subscribeRoomScript (completion notification: subscribeRoomDone ): Before and after subscribing to a room unsubscribeRoomScript (completion notification: unsubscribeRoomDone ): Before and after unsubscribing from a room Push Notifications The main push notifications and their configuration names are as follows: postNotification : Notify when a new post is made in a subscribed room Notification categories can be controlled via notificationTypes , and mobile push forwarding to offline devices can also be configured. Implementation Example Creating a room Room Subscription Room Unsubscribe Posting a message Get a list of messages Message receipt notification handling MessagesAsync responds to the cache if one exists, and the cache of data available in the message list is automatically updated by the SDK when it receives a message receipt notification. Therefore, there is usually no need to handle this event, and by calling MessagesAsync when necessary, the cache can usually be used to access the most recent message list. Other Features Categories that Cannot be Posted from Clients By setting rejectAccessTokenPost to true in the CategoryModel master data, the corresponding category becomes inaccessible for posting using access tokens. This feature can be used to create categories that can only be posted through scripts, useful for storing system messages. Player Room Creation Permission The allowCreateRoom setting in the namespace controls whether players can freely create rooms. allowCreateRoom=true: Players can create their own rooms allowCreateRoom=false: Only rooms prepared by administrators are available Use this setting when you want to prevent excessive room creation or limit available rooms to specific ones. Examples of using message categories Messages can be assigned a category. By using categories, the client can switch how the payload is parsed. For example, the following usage is possible: Category 0 : A regular text message where the text is contained directly in the payload Category 1 : A stamp message where the payload contains the ID of a stamp By dividing categories by message type and importance in this way, players can choose for themselves which types of notifications they want to receive, improving the user experience. Master data management Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: CategoryModel : Whether posts are allowed for each category number ( rejectAccessTokenPost ), and mobile push notification forwarding settings when offline Master data can be registered through the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Detailed Reference Reference of GS2-Chat","lang":"en","section":"microservices","summary":"Text chat feature\n","title":"GS2-Chat","url":"/microservices/chat/"},{"content":"GS2-Datastore allows you to store arbitrary binary data on the server. Uploaded data can have access permissions set: choose from public (open to everyone), protected (visible only to specified user IDs: up to 100), or private (yourself only). GS2-Datastore is primarily intended for uploading data such as UGC or racing-game ghost data, and is not necessarily suitable for storing player user data. This is because storing the quantity of possessions as binary data would allow item duplication via tampering of the save data or the application binary, or play with modded applications that illegally inflate acquired quantities. For something like the quantity of possessions, using a dedicated microservice such as GS2-Inventory prevents such cheating. This is not to deny storing user data that does not affect game balance even if tampered with, such as configuration values. Use cases Typical use cases for GS2-Datastore are as follows: Storing UGC content such as screenshots or replays posted by users Sharing ghost data in racing games Cloud sharing of photos captured in photo mode Storing user data such as game settings whose tampering does not affect game balance Publishing and sharing custom map data for stages Access scope Data objects have three types of access scope, used depending on the purpose. Scope Description Main use public Downloadable by all players Publishing UGC content, ghost sharing protected Downloadable only by users specified in allowUserIds (up to 100) Sharing only with friends private Downloadable only by the user who uploaded it Personal save data, configuration values The scope and allowed users can also be changed later with UpdateDataObject . Architecture GS2-Datastore manages metadata that records the storage location of binary data, and uses external cloud storage for the actual binary data storage. Therefore, the upload/download process requires multiple steps. This process flow is wrapped behind high-level APIs in game-engine SDKs and is nothing you need to be concerned with, but SDKs for various programming languages do not provide a high-level API, so users have to handle the multiple steps themselves. Upload process sequenceDiagram actor Player as Player participant Namespace as GS2-Datastore#Namespace participant Storage as Cloud Storage Player-\u003e\u003eNamespace: PrepareUpload Namespace--\u003e\u003ePlayer: Cloud Storage URL Player-\u003e\u003eStorage: Upload Payload Storage--\u003e\u003ePlayer: OK Player-\u003e\u003eNamespace: DoneUpload Namespace-\u003e\u003eStorage: Check exists Namespace--\u003e\u003ePlayer: OK Download process sequenceDiagram actor Player as Player participant Namespace as GS2-Datastore#Namespace participant Storage as Cloud Storage Player-\u003e\u003eNamespace: PrepareDownload Namespace--\u003e\u003ePlayer: Cloud Storage URL Player-\u003e\u003eStorage: Download Storage--\u003e\u003ePlayer: Payload Downloading during the upload process GS2-Datastore can update data that has already been uploaded. During the time between calling Prepare ReUpload and Done Upload, the old file before the update remains downloadable, so no half-finished data will be downloaded. Retrieving past versions of uploaded data GS2-Datastore provides access to past versions of data for the past 30 days. By retrieving the update history of a data object (DataObjectHistory), you can obtain the generation ID for each past generation and download data by specifying that generation ID. This also applies to deleted data; the data is actually deleted 30 days after a deletion request. However, this condition may not apply when data has been deleted due to legal requirements. Data size and status The maximum size of a single data object is 10MB. During upload the status is UPLOADING ; once complete it becomes ACTIVE ; and after a deletion request it transitions to DELETED . Data in the DELETED state can be restored within 30 days using restoreDataObject . stateDiagram-v2 [*] --\u003e UPLOADING: PrepareUpload UPLOADING --\u003e ACTIVE: DoneUpload ACTIVE --\u003e UPLOADING: PrepareReUpload ACTIVE --\u003e DELETED: DeleteDataObject DELETED --\u003e ACTIVE: RestoreDataObject (within 30 days) DELETED --\u003e [*]: After 30 days Main attributes of a data object Attribute Description dataObjectId Unique ID (GRN) of the data object name Data object name. Unique per user userId ID of the user who uploaded scope Access scope ( public / protected / private ) allowUserIds List of user IDs allowed to reference under the protected scope platform Platform information used for the upload status Data state ( UPLOADING / ACTIVE / DELETED ) generation Identifier of the current generation previousGeneration Identifier of the previous generation Script Triggers Event triggers can be configured to invoke GS2-Script before and after the upload completion notification of a data object. Synchronous execution can be used to reject the completion report, and asynchronous execution enables external integration through Amazon EventBridge. Main event triggers and script setting names are: doneUploadScript (completion notification: doneUploadDone ): before and after the upload completion report By rejecting an upload in a synchronous script, operations such as inspecting the contents of an image with an external service and refusing registration if it is inappropriate content are possible. Implementation Example Uploading data Uploading data consists of three steps — PrepareUpload → PUT to cloud storage → DoneUpload — but in game-engine SDKs it can be completed with a single UploadAsync call. Re-uploading existing data Use re-upload when you want to write new binary data to a data object with the same name. During re-upload, the old data before the update can still be retrieved until DoneUpload is called. Download data (specify data object ID) Download data (specify user ID and data object name) Download data uploaded by yourself (specify data object name) Get a list of data you uploaded Change the access scope of a data object Using UpdateDataObject , you can change the access scope and the list of allowed users later. For example, it is possible to first create a data object as private and switch it to public once it is ready to be shared. Delete a data object Within 30 days after the deletion request, the data can be restored using RestoreDataObject . Get update history of a data object By retrieving past generations, you can implement rollback or browse past replays. Restricting access to older generations of data When downloading data, a generation ID is specified to identify the exact file. Including the generation ID in a download request ensures that you reliably download the data as it was at the time it was listed. However, it is not always desirable for old generation data to remain accessible indefinitely. For this reason, there is an option that, except for the owner of the data, only allows downloading older generation data within 60 minutes of an update and only for the immediately previous generation. Detailed Reference Reference of GS2-Datastore","lang":"en","section":"microservices","summary":"Binary data storage feature\n","title":"GS2-Datastore","url":"/microservices/datastore/"},{"content":"GS2-Deploy provides the ability to manage namespaces and master data of GS2 microservices as code, and to provision them declaratively. Designed with a philosophy similar to AWS CloudFormation, it allows you to build, update, and delete resources spanning multiple microservices as a single unit (a stack) based on resource definitions described in a template file. In game development, adjustments to master data and changes to namespace configurations occur frequently. By using GS2-Deploy, you can manage these changes in Git, and run CI/CD pipelines linked with repositories such as GitHub to deploy them automatically. Stack A stack is a unit that bundles GS2 resources for management. A stack is created based on a YAML-formatted template, and according to the resource definitions described in the template, namespaces and master data are automatically created, updated, or deleted. A single stack can contain resources spanning multiple microservices, allowing a related set of configurations that compose a game to be handled as a single unit. graph LR Template[\"Template (YAML)\"] --\u003e Stack[\"Stack\"] Stack --\u003e R1[\"GS2-Account Namespace\"] Stack --\u003e R2[\"GS2-Inventory Master Data\"] Stack --\u003e R3[\"GS2-Mission Master Data\"] Stack --\u003e R4[\"GS2-Showcase Master Data\"] A stack internally has the following states. CREATE_PROCESSING : Creation in progress CREATE_COMPLETE : Creation completed and resources available UPDATE_PROCESSING : Update in progress UPDATE_COMPLETE : Update completed ROLLBACK_PROCESSING : Rollback in progress after a failure ROLLBACK_COMPLETE : Rollback completed DELETE_PROCESSING : Deletion in progress DELETE_COMPLETE : Deletion completed If a stack update fails midway, a “rollback” process is performed automatically to restore the previous state. Template Templates are written in YAML. The following sections are described. GS2TemplateFormatVersion : Template format version Description : Description of the stack Resources : Definitions of resources to be created Outputs : Definitions of values that can be referenced from other systems after the stack is created Below is an example of a template. GS2TemplateFormatVersion: \"2019-05-01\" Description: | GS2-Account namespace Resources: Namespace: Type: GS2::Account::Namespace Properties: Name: namespace-0001 Description: anonymous account ChangePasswordIfTakeOver: true Outputs: NamespaceId: !GetAttr Namespace.Item.NamespaceId Type specifies the kind of GS2 resource to create, and Properties specifies the resource-specific configuration values. By using the !GetAttr function, you can chain dependent resources by referencing the output values of other resources. Resource Each individual GS2 resource created within a stack is called a “resource”. A resource holds the following information. type : The type of resource (such as GS2::Account::Namespace ) name : The logical name assigned within the template request : The request payload sent to the GS2 API when creating the resource response : The response from the GS2 API rollbackContext : Information used when a rollback is executed By referring to the stack, you can see at a glance the creation status of all resources contained in the stack. Output Values declared in the Outputs section of a template are saved as output values that can be referenced from other places after the stack has been created. Outputs can be used for integration with external systems, for referencing values from other stacks, or for operational tools to retrieve the GRN of GS2 resources. Event Each individual operation that occurs during the creation, update, or deletion of a stack is recorded as an “event”. If a stack operation fails, you can identify at which resource and which stage the failure occurred by reviewing the event history. GitHub Integration In addition to uploading template files directly from the GS2 management console, you can also retrieve them by integrating with a GitHub repository. By using GitHub integration, the following operations become possible. A workflow for reviewing and merging master data configuration changes based on pull requests A pipeline that, triggered by a merge into the main branch, calls GS2-Deploy from CI to update resources Multi-environment operation with different branches and stacks assigned to each environment (development, staging, production) A GitHub API access token is used to retrieve templates from GitHub. Private repositories are also supported. Managing master data as code One of the main use cases of GS2-Deploy is to register the master data of each microservice via a GS2-Deploy template. By describing the master data content in the same template as the namespace definitions, you can manage namespace creation and master data registration in a single stack. This allows you to track the change history of master data in Git, making it easy to roll back to past versions or preview changes before review. About operation targets Because GS2-Deploy is a management API responsible for project provisioning, in principle it is not a service called from game engine clients (Unity / Unreal Engine, etc.). In practice, operations are mainly performed through the management console, or via a workflow that calls the GS2 SDK from CI/CD pipelines. Example Implementation GS2-Deploy is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Therefore, instead of calling it directly from the game client, we recommend operating it via one of the following means. Management console GS2 CLI General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) Declarative management via GS2-Deploy’s own templates For details on each SDK, see the corresponding reference page. Detailed Reference Reference of GS2-Deploy","lang":"en","section":"microservices","summary":"Master data CI/CD feature\n","title":"GS2-Deploy","url":"/microservices/deploy/"},{"content":"This is the format specification of the template file used when creating a stack in GS2-Deploy. It can be written in JSON or YAML format. Types of sections A template consists of the following sections. Section Required Description GS2TemplateFormatVersion  Specifies the format of the template. Currently only 2019-05-01 can be defined. Description You can fill in the description and other information about the template. Globals This section defines the Alias attribute (string replacement specification). Resources  Define resources for each GS2 service to be included in the stack. Outputs Defines the output values to be displayed in the management console. Globals Alias Replaces strings in the Resources and Outputs sections with the specified string. Replace the string on the left side with ${…} The string on the right side is replaced by the string on the left side, enclosed in ${}, as in the following example. Example of replacement specification: ${AccountNamespaceName} Resources Defines the resource to be generated, with Type and Properties attributes, and DependsOn attribute if necessary. Type Specifies resources to be generated for the service. Specify the entity name from the GS2-Deploy reference page for each service. Example: Type: GS2::Account::Namespace . Properties Specify the value to be given to the property value when the resource is created. DependsOn Specifies the name of a dependent resource so that the resource will be created following other resources. Outputs Defines the output values that will hold the value and allow the value to be viewed later, e.g., through the management console. Functions Functions are available in GS2-Deploy templates. !GetAttr The !GetAttr tag can be used to retrieve the property values of the generated results for each resource. In this example, GS2::Account::Namespace is specified in AccountNamespace , so Namespace is generated in GS2-Account. The result is retrieved in AccountNamespace , and the NameSpace model is stored in AccountNamespace.Item.GetAttr AccountNamespace.Item . !GetAttr tag is assigned the following as reserved words, and the values can be retrieved. Key Value Type Description Gs2::Region string Region type Gs2::OwnerId string Owner ID !Join The !Join tag concatenates the strings in the following array. A delimiter (delimiter) can be specified. Format: !Join [ specify delimiter, [list of strings to concatenate]]","lang":"en","section":"articles","summary":"Information about GS2-Deploy template file specification\n","title":"GS2-Deploy template file specification","url":"/articles/tech/deploy/"},{"content":"GS2-Dictionary provides a dictionary (compendium) function for items and characters acquired in the game. Basically, you can think of it as a simple-implementation version of GS2-Inventory, which manages a two-state (acquired / not acquired) ownership status. It can also be used for purposes other than a dictionary. For example, the ownership status of avatar parts is a good example. Whether you own a particular avatar part is sufficient to manage as a two-state per part, so GS2-Dictionary is well suited for this. It can also be applied broadly to any element that can be expressed as a binary state, such as managing completed tutorial steps, unlocked cutscenes, or a list of unlocked BGM tracks. graph TD Boss[\"Defeat a boss\"] -- Add entry as reward --\u003e Dictionary[\"Record in GS2-Dictionary\"] Shop[\"Purchase from shop\"] -- Add entry as reward --\u003e Dictionary Dictionary --\u003e Browse[\"Player browses the dictionary\"] Dictionary -- Possession-proof signature --\u003e Formation[\"Used by GS2-Formation, etc.\"] Differences from GS2-Inventory Presence of the stack concept GS2-Inventory has the concept of stacking when holding multiple copies of the same item. For example, potions can be stacked up to 99, and a second stack is created when more than 99 are held. Because of this specification, in GS2-Inventory the return value of the API for “get the quantity of potions held” is a list. This is because there may be multiple stacks of potions. This specification is convenient for managing data such as potions, but it is over-spec for managing a simple possession status like a dictionary, and handling lists also increases the amount of code written. Multiple entries can be registered in a single acquisition GS2-Inventory requires acquiring a potion and acquiring an elixir to be handled in separate API requests. GS2-Dictionary can register up to 100 entries in a single API request. This allows operations such as “register all defeated monster species in the dictionary at once” as a quest clear reward to be efficiently performed in a single request. Verification and deletion of entries GS2-Dictionary allows you to delete entries that have been recorded, or to verify whether a specific entry has been acquired (or not acquired). This enables operations such as resetting the possession status of limited-time event items, or restricting quests so that they can only be started when a specific item has been acquired. Feature comparison Item GS2-Dictionary GS2-Inventory State management Two-state: owned / not owned Quantity / stack management Entries per request Up to 100 One at a time Favorites Yes No Possession-proof signature Yes Yes (per ItemSet) Main use Dictionary, avatar parts, unlock state Ordinary item possession Master data (EntryModel) Entries that can be registered in the dictionary are defined as master data. The main configuration items of EntryModel are as follows. Item Description name Entry name (record key per player) metadata Arbitrary metadata used by the client (display name, image reference, rarity, etc.) Example master data JSON: { \"version\": \"2020-04-30\", \"entryModels\": [ { \"name\": \"monster-0001\", \"metadata\": \"{\\\"displayName\\\":\\\"Slime\\\",\\\"rarity\\\":1}\" }, { \"name\": \"monster-0002\", \"metadata\": \"{\\\"displayName\\\":\\\"Goblin\\\",\\\"rarity\\\":2}\" } ] } Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Favorites feature GS2-Dictionary allows you to mark recorded entries as favorites. Use AddLikes or DeleteLikes to manage the favorites list, and use the Likes API to retrieve them or subscribe to change notifications. By using favorite information, you can implement filtering on the dictionary screen or prioritized display in the UI. Favorite entries are internally stored in a unit called LikeToc , so a user can efficiently retrieve a large number of favorites. Possession-proof signature GS2-Dictionary can issue signed data for the possession status of an entry. When integrating with other GS2 microservices, this allows you to guarantee “the player really does own that entry” without server-to-server communication. sequenceDiagram participant Player participant Dictionary as GS2-Dictionary participant Formation as GS2-Formation Player -\u003e\u003e Dictionary: GetEntryWithSignature(entry, keyId) Dictionary --\u003e\u003e Player: Body + Signature Player -\u003e\u003e Formation: SetForm(itemId, body, signature) Formation -\u003e\u003e Formation: Verify signature Formation --\u003e\u003e Player: Success The verifying service can validate the information contained in body (such as the entry name and user ID) using signature . Script triggers By setting entryScript or duplicateEntryScript in the namespace, you can invoke custom scripts before/after entry registration or when a duplicate registration occurs. Scripts can be executed synchronously or asynchronously; asynchronous execution also enables external integration via GS2-Script or Amazon EventBridge. Main event triggers and script setting names are: entryScript (completion notification: entryDone ): before and after entry registration duplicateEntryScript : when re-registering an already registered entry Using duplicateEntryScript , you can implement conversion logic such as “when a rare monster that is already registered in the dictionary is dropped again, grant a different currency instead”. Transaction actions GS2-Dictionary provides the following transaction actions: Verify action: Verify entry possession status Consume action: Delete entries Acquire action: Add entries By using “Verify entry possession status” as a verify action, you can impose restrictions such as a quest that only players who have defeated a specific monster (and thus registered it in the dictionary) can attempt, or a product that can only be purchased by players who have acquired a specific item at least once. How to record in the dictionary Recording in the dictionary (adding an Entry ) cannot be called directly from the game-engine SDKs. This is by design of the GS2 security model: arbitrary client-side rewrites are prohibited, and entries are only added through paths trusted by the server. Specifically, it is incorporated as a transaction action in forms such as the following: Set an acquire action that “registers the defeated monster in the dictionary” as a clear reward of a GS2-Quest quest Set an acquire action that “registers the corresponding entry in the dictionary” as a reward for an item purchased in GS2-Showcase Set an acquire action that “registers a specific entry” as a mission completion reward of GS2-Mission Implementation Example Get a list of master data that can be recorded in the dictionary Get the list of entries recorded in the dictionary Get a specific entry Obtaining a possession-proof signature When linking with other microservices within GS2, you may be required to provide data that guarantees an entry really has been recorded in GS2-Dictionary. For example, suppose GS2-Dictionary manages the possession status of avatar parts and GS2-Formation manages how avatar parts are equipped. When setting a hairstyle in GS2-Formation, an API request is made to set the part “hair-0001”, but GS2-Formation requires that “hair-0001” be specified together with a possession-proof signature. This way, GS2-Formation does not need to communicate with GS2-Dictionary behind the scenes to determine whether the part is really owned. Adding favorite entries Listing favorite entries Deleting favorite entries Detailed Reference Reference of GS2-Dictionary","lang":"en","section":"microservices","summary":"Dictionary feature\n","title":"GS2-Dictionary","url":"/microservices/dictionary/"},{"content":"GS2-Distributor is the core service for executing transactions that span across multiple GS2 microservices. It provides the foundation for safely executing a sequence of operations that span multiple microservices, such as “consume an item to receive a reward” or “consume stamina to start a quest”. In GS2, operations that are disadvantageous to the player are called “consume actions”, and operations that are advantageous are called “acquire actions”. GS2-Distributor receives a “transaction” that bundles these actions together, then forwards and executes them against the appropriate microservices, allowing all of the processing that makes up the game cycle to be handled in a consistent manner. For more details on how transactions work, see Transaction . Actions that compose a transaction A GS2 transaction is composed of the following three types of actions. graph LR Issue[\"Transaction Issued (Store / Quest / Mission, etc.)\"] --\u003e Verify[\"Verify Action\"] Verify --\u003e Consume[\"Consume Action\"] Consume --\u003e Acquire[\"Acquire Action\"] Acquire --\u003e Done[\"Done\"] Verify Action An action that checks in advance, before starting transaction execution, whether the consume actions and acquire actions can be performed. For example, conditions such as “must possess a specific item”, “rank must be at or above a certain value”, or “a specific quest must already be cleared” can be checked before any consumption occurs. If verification fails, the consume and acquire actions are not executed. Consume Action An action that represents processing that is disadvantageous to the player. This includes consuming items, consuming currency, consuming stamina, incrementing a usage limit counter, and similar operations. When a consume action is executed, each microservice issues a signature proving that “it has been executed”. This signature is verified when the next acquire action is executed, and the acquire action cannot run unless all consume actions have been passed. Acquire Action An action that represents processing that is advantageous to the player. This includes acquiring items, acquiring currency, gaining experience, starting a quest, and similar operations. An acquire action is executed only when the signatures indicating that all related consume actions have completed successfully are collected. Structure of a transaction A GS2 transaction is issued in the structure of “multiple consume actions + one acquire action”. Transactions are returned as the response of transaction issuance APIs from each microservice such as GS2-Showcase / GS2-Quest / GS2-Mission, and the game client executes the obtained transaction through GS2-Distributor. The GS2 SDK includes a mechanism that automatically executes transactions, and in most cases the game side does not need to be conscious of transaction execution. Simply calling WaitAsync on the TransactionDomain included in the issuance API result causes the consume and acquire actions to be executed in the correct order and the result to be retrieved. DistributorModel A DistributorModel is a unit of resource distribution configuration registered within a namespace. The following can be configured for a DistributorModel: inboxNamespaceId : GRN of the GS2-Inbox namespace to which contents are automatically forwarded if they overflow. whiteListTargetIds : Whitelist of actions allowed to be executed via transactions. By preparing multiple DistributorModels, you can use different forwarding rules for different purposes such as store, quest, and mission. Overflow handling for distributions When executing an acquire action, the result may not be receivable on the spot due to reasons such as exceeding the player’s holding limit. To prepare for such cases, setting the inboxNamespaceId of the DistributorModel will automatically forward the undelivered content as a message to GS2-Inbox, allowing the player to receive it later. This prevents situations where rewards are lost because they could not be received. graph TD Acquire[\"Execute Acquire Action\"] --\u003e Check{\"Grantable to player?\"} Check -- Yes --\u003e Granted[\"Grant to player\"] Check -- \"No (limit exceeded, etc.)\" --\u003e Inbox[\"Forward to GS2-Inbox\"] Inbox --\u003e Receive[\"Player receives later\"] Batch Request GS2-Distributor provides a “batch request” feature that bundles multiple GS2 API calls into a single request for execution. Since multiple service queries can be completed in a single API call, this reduces network round trips and improves response time. It is especially useful in cases such as fetching initial data from multiple microservices at game startup. Each request included in a batch request is processed independently, and a response is returned for each. Master Data Management Registering master data allows you to configure data and behaviors available to the microservice. Master data types include: DistributorModel : Transaction forwarding rules and the forwarding destination on overflow Below is a JSON example of master data: { \"version\": \"2019-09-09\", \"distributorModels\": [ { \"name\": \"default\", \"metadata\": \"default distributor\", \"inboxNamespaceId\": \"grn:gs2:{region}:{ownerId}:inbox:namespace-0001\" } ] } Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy. Transaction Actions GS2-Distributor is the service that executes transactions issued by other services, and it does not itself issue consume or acquire actions. Example Implementation Executing a transaction In the GS2 SDK, calling WaitAsync on the TransactionDomain returned by each service’s transaction issuance API automatically executes the transaction through GS2-Distributor. Below is an example of executing a transaction using the GS2-Mission reward receipt process. Executing a batch request Multiple GS2 API calls are executed in a single round trip. Freezing master data If master data is updated after a transaction has been issued, inconsistencies may arise between the issued transaction and the current master data. By calling FreezeMasterData of GS2-Distributor, the master data version used for the logged-in player is fixed, avoiding inconsistencies caused by switching master data during gameplay. Detailed Reference Reference of GS2-Distributor","lang":"en","section":"microservices","summary":"Transaction processing feature\n","title":"GS2-Distributor","url":"/microservices/distributor/"},{"content":"This service provides a feature for adding unique random parameters to equipment and characters. It can be used to implement expressions such as additional stats on weapons in an RPG, individual values granted to cards obtained from gacha, or additional effects on equipment in hack-and-slash games — i.e., representations where “even the same item has different performance for each individual instance”. Two types of random parameters are available: Balance parameter Rarity parameter graph TD Item[\"Equipment, character, etc. (identified by propertyId)\"] --\u003e Choose{Parameter type} Choose -- Distribute a total amount --\u003e Balance[\"Balance Parameter e.g. ATK 60 / DEF 40\"] Choose -- Grant multiple by probability --\u003e Rarity[\"Rarity Parameter e.g. Critical Rate +5%, HP +100\"] Balance --\u003e ReDraw1[\"Re-draw / Set value directly\"] Rarity --\u003e ReDraw2[\"Re-draw / Add / Set value directly\"] Random parameters are managed using propertyId , the “identifier of the target item”, as a key. By specifying values such as a GS2-Inventory item instance ID or a GS2-Formation form identifier as propertyId , parameters can be associated with each individual piece of equipment. Balance parameter A balance parameter randomly distributes multiple prepared parameters within a fixed total amount. For example, if two parameters — attack and defense — are prepared and the total is set to 100, and attack is drawn at 60, then defense becomes 40. Master item Description name Balance parameter model name totalValue Total amount distributed across parameter values initialValueStrategy How the initial value is determined ( average : average value / random : random) parameters List of parameters that are the distribution targets Re-drawing Balance parameters can be re-drawn. Some parameter values can be fixed when re-drawing. By fixing some parameters, you can provide players with a means of efficiently optimizing their parameters. Initial values You can decide whether the initial values of balance parameters are random or use the average value. Setting values directly Balance parameters can also be set directly to arbitrary values without a draw, via the management console or API (transaction action). This makes it possible to distribute equipment with fixed stats as a specific event reward. Rarity parameter Unlike balance parameters, which distribute values across a fixed set of parameters, rarity parameters can be used in cases where additional parameters are granted to equipment or skills with a certain probability. In the master data, you first set the draw probability for the number of parameters to be granted. Then, set the type and probability of each parameter to be granted. This allows additional parameters to be granted based on probability. Master item Description name Rarity parameter model name maximumParameterCount Maximum number of parameters that can be granted to a single propertyId parameterCounts The number granted and its weight (weighted draw) parameters Individual parameters and the weight that becomes the probability of being granted Each parameter ( RarityParameterValueModel ) can be configured with resourceName / resourceValue to express which resource the granted result references and by how much. Re-drawing Granted parameters can be re-drawn; when re-drawn, only the types of granted parameters change, not the number. As with balance parameters, some of the parameters being re-drawn can be fixed. Adding Rarity parameters can be added later. When adding, existing parameters remain unchanged, and the specified number of additional parameters can be added. Setting values directly Rarity parameters can also have the types of granted parameters and their values set directly, via the management console or API (transaction action). As with balance parameters, this enables distribution of items with guaranteed specific performance. Transaction Actions GS2-Enchant provides the following transaction actions. These can be used to manipulate parameters through quest rewards, shop purchases, and so on. Verify actions Action Use Gs2Enchant:VerifyRarityParameterStatus Verifies the possession state of a rarity parameter (held / not held) or count. Switch the behavior by specifying havent , have , or count for verifyType . Acquire actions Action Use Gs2Enchant:ReDrawBalanceParameterStatusByUserId Re-draws a balance parameter. The names of parameters to be fixed can be specified in fixedParameterNames . Gs2Enchant:SetBalanceParameterStatusByUserId Directly overwrites a balance parameter without a draw. Gs2Enchant:ReDrawRarityParameterStatusByUserId Re-draws a rarity parameter. The names of parameters to be fixed can be specified. Gs2Enchant:AddRarityParameterStatusByUserId Performs an additional draw of the specified count while keeping existing rarity parameters. Gs2Enchant:SetRarityParameterStatusByUserId Directly overwrites rarity parameters without a draw. Master data operations Registering master data allows you to configure data and behaviors available to the microservice. Master data types include: BalanceParameterModel : Parameter distribution settings RarityParameterModel : Granted parameters and probability settings Below is an example of master data JSON: { \"version\": \"2023-04-27\", \"balanceParameterModels\": [ { \"name\": \"balance-0001\", \"metadata\": \"weapon\", \"totalValue\": 100, \"initialValueStrategy\": \"average\", \"parameters\": [ { \"name\": \"attack\", \"metadata\": \"ATK\" }, { \"name\": \"defense\", \"metadata\": \"DEF\" } ] } ], \"rarityParameterModels\": [ { \"name\": \"rarity-0001\", \"metadata\": \"weapon\", \"maximumParameterCount\": 4, \"parameterCounts\": [ { \"count\": 1, \"weight\": 70 }, { \"count\": 2, \"weight\": 25 }, { \"count\": 3, \"weight\": 5 } ], \"parameters\": [ { \"name\": \"critical\", \"weight\": 50, \"resourceName\": \"critical\", \"resourceValue\": 5 }, { \"name\": \"hp\", \"weight\": 50, \"resourceName\": \"hp\", \"resourceValue\": 100 } ] } ] } Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Example implementation Balance Parameter Parameter initialization / retrieval When parameter information is retrieved for the first time, the parameter drawing process is created. Referencing parameter values From ParameterValues of the EzBalanceParameterStatus obtained with ModelAsync , you can retrieve each parameter name and its current value. Parameter re-drawing Re-drawing cannot be handled by the SDK for game engines. From within the game, perform re-drawing by executing a transaction action such as Gs2Enchant:ReDrawBalanceParameterStatusByUserId via GS2-Distributor. Rarity Parameter Parameter initialization / retrieval When parameter information is retrieved for the first time, the parameter drawing process is created. Parameter verification You can have the server verify whether a rarity parameter has been granted, or whether a specific number has been granted. This is useful for condition checks such as “only allow equipment with a specific parameter” during gacha or enhancement processes. Parameter re-drawing Re-drawing cannot be handled by the SDK for game engines. From within the game, perform re-drawing by executing a transaction action such as Gs2Enchant:ReDrawRarityParameterStatusByUserId via GS2-Distributor. Adding parameters Adding parameters cannot be handled by the SDK for game engines. Add them by executing Gs2Enchant:AddRarityParameterStatusByUserId via GS2-Distributor. Detailed Reference Reference of GS2-Enchant","lang":"en","section":"microservices","summary":"Enchantment(random parameter) feature","title":"GS2-Enchant","url":"/microservices/enchant/"},{"content":"This feature may be completely incomprehensible to some developers. However, it is a feature that is always present in the de facto standard game systems of mobile games, starting with those in Japan. This game mechanic itself should be useful knowledge for realizing Game as a Service, so for developers who do not understand it we add an explanation of the game mechanism. If you already have sufficient knowledge of the game mechanics of the enhancement feature, you can safely skip the rest of this explanation section. Game mechanics of the enhancement feature Enhancement itself is a very simple game system in which material items can be consumed to add experience to a target. In addition to the method of gaining experience by participating in battle, characters and equipment can be grown in a variety of ways. (Equipment also has levels.) Now let us explain why this game system plays a role in realizing Game as a Service. In a nutshell, it is used to pad play time. You all surely understand that the speed of game play is overwhelmingly faster than the speed of game development. A game that we game developers spent three years building, players finish in 10 hours. But Game as a Service cannot be sustained if this gap is not closed. In other words, it is necessary to debuff the rate at which players consume content. That magic is the enhancement game system. A typical Game as a Service game holds an event once per month. In each event there is some kind of boss, and the player keeps defeating that boss repeatedly throughout the event period. The bosses come in multiple difficulties matched to the player’s growth stage, and defeating them yields character and equipment enhancement materials. Using the enhancement materials they have gathered, players convert them into experience for characters and equipment to grow them. As characters and equipment grow, they can challenge higher difficulties of the boss. In this way, while all players participate in the event, they obtain enhancement materials suited to their character’s growth stage and enjoy the gameplay of growing characters and equipment. In reality, bosses rarely drop enhancement materials directly. Instead, there may be a gacha that can only be challenged during the event period and players collect points to draw it and obtain materials through the gacha, or there may be a shop open only during the event period where players collect in-game currency from defeating bosses and purchase enhancement materials from the shop. There are various designs that let players decide where to prioritize their growth, but ultimately what is happening is that the time a player needs to grow their character is being stretched to pad play time. What remains consistent throughout the event is that the player’s character becomes stronger. Once the event ends, the stronger character is used to enjoy higher-difficulty permanent content, leading into the next form of fun. graph TD BossBattle[\"Boss Battle\"] -- Acquire Event Point --\u003e Shop Shop -- Buy Enhance Materials --\u003e Enhance[\"Enhance Character\"] Enhance -- More Formidable --\u003e BossBattle Architecture Enhancement is realized by GS2-Enhance operating on GS2-Inventory, which manages the items used as materials, and either GS2-Inventory or GS2-Dictionary, which manages the target character or equipment, plus GS2-Experience, which manages the experience and levels of that character or equipment. In the current GS2, enhancement via DirectEnhance , which completes the consumption and experience addition in a single API request, is recommended. Previously, because automatic transaction execution was not available, a multi-step enhancement process ( Progress ) divided into preparation, execution, and completion reporting was recommended to prevent acts such as cutting off communication and retrying until a great success appeared. Now that automatic transaction execution and atomic commit mechanisms are in place, that concern has been resolved. actor Player participant \"GS2-Enhance#Namespace\" participant \"GS2-Inventory#ItemSet(Material)\" participant \"GS2-Experience#Status\" Player -\u003e \"GS2-Enhance#Namespace\" : Direct Enhance(Materials/Target Character) \"GS2-Enhance#Namespace\" -\u003e \"GS2-Inventory#ItemSet(Material)\" : Get experience value from metadata \"GS2-Enhance#Namespace\" -\u003e \"GS2-Inventory#ItemSet(Material)\" : Consume \"GS2-Enhance#Namespace\" -\u003e \"GS2-Experience#Status\": Add experience(Key: Target Character/Equipment Id) \"GS2-Enhance#Namespace\" -\u003e Player : Enhance result You call the enhancement execution API ( DirectEnhance ) on GS2-Enhance with the parameters of “enhancement target” and “materials used for enhancement”. GS2-Enhance then retrieves the master data of the material item from GS2-Inventory and obtains, from its metadata, the amount of experience to gain when used as material. Once the amount of experience is determined, the item is consumed and the experience-addition process is executed on GS2-Experience. Although an enhancement target is specified, it is only used as the key for the experience managed by GS2-Experience; the enhancement target’s information itself is not used directly. Differences between DirectEnhance and Progress GS2-Enhance provides two enhancement flows. Item DirectEnhance Progress (Start / End) Number of API calls 1 2 (start / end) Recommended use All enhancement processing When you want to obtain a draw result in advance to reflect outcomes such as great success in your effects Atomicity Consumption and experience addition complete within the request The draw result is held on the server and confirmed by a subsequent End Abuse via disconnect None An in-progress Progress can only be held one at a time; retries are only possible via DeleteProgress Unless there is a special requirement, we recommend using DirectEnhance . sequenceDiagram participant Player participant Enhance as GS2-Enhance participant Inventory as GS2-Inventory participant Experience as GS2-Experience Player -\u003e\u003e Enhance: DirectEnhance(rateName, targetItemSetId, materials) Enhance -\u003e\u003e Inventory: Obtain experience amount from metadata Enhance -\u003e\u003e Inventory: Consume material items Enhance -\u003e\u003e Experience: Add experience Enhance --\u003e\u003e Player: Added experience and great-success multiplier Enhancement Rate To limit the materials that can be used for enhancement and the enhancement target, the enhancement rate must be set as master data. Master data records information such as the GS2-Inventory namespace and inventory name of items that can be used as materials, and the GS2-Inventory namespace and inventory name of items that can be enhancement targets. Master data is managed in JSON format. Here is an example of setting metadata for an ItemModel in JSON format such as { \"experience\": 50 } . Define the JSON key ( experience in the example above) in the acquireExperienceHierarchy of the RateModel. acquireExperienceHierarchy can also define a hierarchical structure. For example, if you want to set metadata with a data structure such as { \"aaa\": { \"bbb\": { \"experienceValue\": 100 } } } , specify [ \"aaa\", \"bbb\", \"experienceValue\" ] in acquireExperienceHierarchy . Main configuration items of RateModel Item Description name Enhancement rate name targetInventoryModelId Inventory model ID of the GS2-Inventory holding items to be enhanced materialInventoryModelId Inventory model ID of the GS2-Inventory holding material items acquireExperienceHierarchy JSON path used to extract the experience amount from the material item’s metadata acquireExperienceSuffix Suffix appended to the experience model name key (e.g. :level ) experienceModelId Experience model ID of the GS2-Experience to which experience is added bonusRates Multipliers and weights for great-success draws GS2-Enhance RateModel master data — example of setting experience in metadata: { \"version\": \"2020-08-22\", \"rateModels\": [ { \"name\": \"enhanceRate\", \"description\": \"\", \"metadata\": \"\", \"targetInventoryModelId\": \"grn:gs2:ap-northeast-1:YourOwnerId:inventory:enhance-inventory:model:character\", \"acquireExperienceSuffix\": \":level\", \"materialInventoryModelId\": \"grn:gs2:ap-northeast-1:YourOwnerId:inventory:enhance-inventory:model:material\", \"acquireExperienceHierarchy\": [ \"experience\" ], \"experienceModelId\": \"grn:gs2:ap-northeast-1:YourOwnerId:experience:enhance-experience:model:character\", \"bonusRates\": [ { \"rate\": 2, \"weight\": 1 }, { \"rate\": 1, \"weight\": 1 } ] } ] } bonusRates can hold multiple entries; each entry has a draw weight ( weight ) and multiplier ( rate ). In the example above, “2x experience” and “1x experience” are drawn at the same weight, so a great success (2x) occurs roughly 50% of the time. GS2-Experience ExperienceModel master data example: { \"version\": \"2019-01-11\", \"experienceModels\": [ { \"name\": \"character\", \"metadata\": \"CHARACTER\", \"defaultExperience\": 0, \"defaultRankCap\": 50, \"maxRankCap\": 80, \"rankThreshold\": { \"metadata\": \"RANK_THRESHOLD\", \"values\": [ 100, 300, 500, 1000 ] } } ] } GS2-Inventory ItemModel master data — example of setting experience in metadata: { \"version\": \"2019-02-05\", \"inventoryModels\": [ { \"name\": \"character\", \"initialCapacity\": 1, \"maxCapacity\": 1, \"protectReferencedItem\": false, \"itemModels\": [ { \"name\": \"character-0001\", \"stackingLimit\": 1, \"allowMultipleStacks\": false, \"sortValue\": 0 } ] }, { \"name\": \"material\", \"metadata\": \"\", \"initialCapacity\": 10, \"maxCapacity\": 10, \"protectReferencedItem\": false, \"itemModels\": [ { \"name\": \"material-0001\", \"metadata\": \"{\\\"experience\\\":50}\", \"stackingLimit\": 99, \"allowMultipleStacks\": false, \"sortValue\": 0 } ] } ] } Limit Break (Unleash) A “limit break” feature is also provided that consumes items such as duplicates of the same kind as materials to raise the target’s level cap. It is a mechanism for raising the rankCap managed by GS2-Experience one stage at a time, configured through the master data of UnleashRateModel with the following: The inventory model that is the limit-break target The associated grade model (GS2-Grade) The material items and quantities required to reach each grade This makes it possible to implement game mechanics such as “collect 4 of the same character to limit-break” or “consume N of a specific material item to unlock the level cap”. Script Triggers By configuring enhanceScript on the namespace, you can call custom scripts before and after enhancement execution. You can allow/deny the process or override the gained experience, and choose synchronous or asynchronous execution. Asynchronous execution also supports external integration via GS2-Script or Amazon EventBridge. Main event triggers and script setting names are: enhanceScript (completion notification: enhanceDone ): before and after enhancement execution In the script you can reference the enhancement target, the material items, and the multiplier being drawn. This is useful for purposes such as game balance adjustment or changing the boost multiplier during an event period. Master data operations Registering master data allows you to configure data and behaviors available to the microservice. Master data types include: RateModel : Definition of enhancement materials and targets UnleashRateModel : Rate definitions for limit break Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Transaction Actions GS2-Enhance provides the following transaction actions: Consume action: Delete the in-progress enhancement progress information ( Progress ) Acquire action: Execute immediate enhancement ( DirectEnhance ), execute limit break ( Unleash ), start enhancement ( Progress ) By using “Execute immediate enhancement (DirectEnhance)” as an acquire action, you can perform operations such as directly granting experience to characters or equipment as a reward for clearing a specific quest or purchasing an item from a shop. Also, by setting “Limit break (Unleash)” as a reward, you can implement operations such as automatically raising the level cap when a specific mission is completed. Example implementation Getting a list of enhancement rates Executing enhancement (DirectEnhance) Specify the ItemSetId and quantity of the material items to consume in materials . Pass the ItemSetId of the character/equipment you want to enhance as targetItemSetId . Starting enhancement (Progress) This is the flow when you want to obtain the draw result in advance. Only one in-progress Progress can be held per user. Getting in-progress enhancement information You can obtain the drawn multiplier (great-success flag) and the amount of experience gained, and use them in enhancement effects. Completing enhancement (Progress) Finalize the enhancement started by Start with End , executing consumption and experience addition. Discarding in-progress enhancement information Used for recovery in cases such as when communication is interrupted and the completion report cannot be made. Other features Great success in enhancement In some enhancement specifications, a “great success” occurs at a certain probability, multiplying the gained experience by 1.5x or 2x. With GS2-Enhance you can configure the probability of great success and the experience multiplier in that case as part of the enhancement rate. The ratio of each entry’s weight to the total of bonusRates weight is the probability of that multiplier being drawn. Passing parameters to scripts using Config EnhanceAsync / StartAsync accept a config parameter, which lets you pass arbitrary key-value pairs at script trigger time. You can convey information such as an in-game event boost state or the enhancement mode the player selected to the script. Speculative Execute When the speculativeExecute argument (default true ) is enabled, the client-side cache is updated before waiting for the API response, allowing the UI to immediately display the post-experience-addition state. This delivers a snappy operational feel that is less affected by communication latency. Detailed Reference Reference of GS2-Enhance","lang":"en","section":"microservices","summary":"Enhancement feature\n","title":"GS2-Enhance","url":"/microservices/enhance/"},{"content":"This is one of the most widely used microservices provided by GS2. It is responsible for converting the resources of any microservice into the resources of a completely different microservice. There are many game specifications related to resource exchange, and GS2-Exchange comes into play each time. Examples of resource exchange Conversion of enhancement materials Exchange 10 ★1 enhancement materials managed by GS2-Inventory for 1 ★2 enhancement material also managed by GS2-Inventory. Obtain an item once every 6 hours Exchange 1 stamina, which recovers once every 6 hours, managed by GS2-Stamina, for an item managed by GS2-Inventory. Sell items Exchange items managed by GS2-Inventory for in-game currency also managed by GS2-Inventory. Types of exchange GS2-Exchange has three modes: direct exchange, where exchange happens immediately at the rate defined in master data; asynchronous exchange, where the exchange result is obtained after a certain real-world time has passed after executing the exchange; and cost-increasing exchange, where the cost rises with each purchase. flowchart LR Verify[\"Verify cost (verifyActions)\"] --\u003e Consume[\"Consume cost (consumeActions)\"] Consume --\u003e|timingType=direct| Acquire[\"Grant reward (acquireActions)\"] Consume --\u003e|timingType=await| Await[\"Create Await object\"] Await -. lockTime elapses .-\u003e Acquire2[\"AcquireAsync receives reward\"] The exchange behavior can be enabled per mode through the namespace settings enableDirectExchange / enableAwaitExchange . By switching the timingType of a rate model to direct or await , you can choose whether each individual rate operates as an immediate exchange or as an asynchronous exchange. Behavior of asynchronous exchange When an asynchronous exchange is used, the cost is consumed at the time the exchange is executed, and an Await object is created instead of the reward being granted. Once the exchange wait time defined in master data ( lockTime seconds) elapses from the time the Await object was created, the reward can be received. State Field Time the exchange was executed exchangedAt Time at which the reward becomes acquirable acquirableAt Quantity consumed as cost count Seconds shortened by skipping skipSeconds Strengthening bases In a city-building game, after consuming resources to grow a base, the base’s experience is actually added after 8 hours have elapsed. Expeditions After organizing a party and going on an adventure, the reward of the adventure can be received 3 hours later. Skipping asynchronous exchange You can also allow the wait of asynchronous exchanges to be skipped by paying additional cost. This kind of specification is typically implemented as a monetization feature, but by consuming in-game currency managed by GS2-Money that has been purchased with real money, you can implement a specification where wait times can be shortened. Forced acquisition and deletion of pending rewards Through the management console or API (transaction actions), it is possible to forcibly acquire rewards ignoring the wait time, or to cancel an in-progress asynchronous exchange (Await object) by deleting it. Examples of cost-increasing exchange Enhancement (inflationary game) The amount of gold consumed to enhance increases each time you enhance. Stamina recovery cost increases The amount of paid currency required to purchase stamina increases each time stamina is purchased. The purchase count is reset daily. Calculation of cost increase There are three modes for the amount of cost increase, specified by calculateType of IncrementalRateModel . linear baseValue + (coefficientValue * number of exchanges) Example baseValue = 100, coefficientValue = 50 Number of exchanges Cost 0 100 1 150 2 200 3 250 4 300 power coefficientValue * (number of exchanges + 1) ^ 2 Example coefficientValue = 50 Number of exchanges Cost 0 50 1 200 2 450 3 800 4 1250 gs2_script Calculated based on the result of executing a GS2-Script. Useful when you want to calculate the cost based on complex conditions. Example currentExchangeCount = args.currentExchangeCount quantity = quantity cost = 100 for i = 1 , quantity do cost = cost + (i + currentExchangeCount - 1) * 50 end result = { cost=cost } Number of exchanges Cost 0 100 1 150 2 200 3 250 4 300 Managing the number of exchanges In IncrementalRateModel , by specifying exchangeCountId and maximumExchangeCount , you can integrate with GS2-Limit’s count restriction model to track the number of exchanges executed, or set an exchange limit within a specific period. If you specify a GS2-Limit Counter model as exchangeCountId , the exchange count is tracked in GS2-Limit and can be reset daily, weekly, etc., according to GS2-Limit’s reset specification. Exchanges that exceed maximumExchangeCount are rejected, which makes it possible to implement gachas with a per-period purchase limit, or item shops where you can purchase only N times per day. Master data operations Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: RateModel : Rate definitions for immediate or asynchronous exchanges IncrementalRateModel : Rate definitions where cost increases with the number of exchanges Main fields of RateModel Field Description name Rate name (unique) verifyActions Verify actions performed before executing the exchange consumeActions Actions consumed as the cost acquireActions Actions granted as the reward timingType direct (immediate exchange) / await (asynchronous exchange) lockTime Wait seconds of asynchronous exchange Main fields of IncrementalRateModel Field Description name Rate name (unique) consumeAction Action consumed as cost (quantity is determined by the cost calculation) acquireActions Actions granted as reward calculateType Cost calculation method ( linear / power / gs2_script ) baseValue / coefficientValue Coefficients used in cost calculation calculateScriptId Script invoked when using gs2_script exchangeCountId GS2-Limit counter that manages the exchange count maximumExchangeCount Upper limit on the number of exchanges JSON example of master data { \"version\": \"2019-08-19\", \"rateModels\": [ { \"name\": \"material_n_to_r\", \"metadata\": \"N -\u003e R enhancement material exchange\", \"consumeActions\": [ { \"action\": \"Gs2Inventory:ConsumeItemSetByUserId\", \"request\": \"{\\\"namespaceName\\\":\\\"inventory-0001\\\",\\\"inventoryName\\\":\\\"material\\\",\\\"itemName\\\":\\\"n-material\\\",\\\"userId\\\":\\\"#{userId}\\\",\\\"consumeCount\\\":10}\" } ], \"timingType\": \"await\", \"lockTime\": 3600, \"acquireActions\": [ { \"action\": \"Gs2Inventory:AcquireItemSetByUserId\", \"request\": \"{\\\"namespaceName\\\":\\\"inventory-0001\\\",\\\"inventoryName\\\":\\\"material\\\",\\\"itemName\\\":\\\"r-material\\\",\\\"userId\\\":\\\"#{userId}\\\",\\\"acquireCount\\\":1}\" } ] } ] } Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. Script Triggers By adding the following script settings to a namespace, you can run custom scripts before and after exchange processing or pending reward retrieval. Main event triggers and script setting names are: exchangeScript (completion notification: exchangeDone ): before and after exchange processing incrementalExchangeScript (completion notification: incrementalExchangeDone ): before and after cost-increasing exchange acquireAwaitScript (completion notification: acquireAwaitDone ): before and after acquiring a pending reward These scripts can be executed synchronously or asynchronously, with asynchronous execution also supporting external integration via GS2-Script or Amazon EventBridge. When calculateType gs2_script is selected on an IncrementalRateModel , the calculateScriptId configured per rate is invoked to calculate the cost. Correction by Buff When linked with GS2-Buff, you can dynamically override lockTime , acquireActions , verifyActions , and consumeActions of a RateModel , and acquireActions , consumeAction , and maximumExchangeCount of an IncrementalRateModel via the context stack. This allows flexible adjustment of rewards, wait times, and exchange limits for events or campaigns. For example, you can implement measures such as “halving the wait time for enhancement material exchanges for a limited period” or “raising the daily gacha purchase limit” by simply applying a buff, without rewriting master data. Implementation Example Executing an exchange (direct) The config parameter accepts context values used in the transactions of the cost/reward actions associated with the exchange. Starting an asynchronous exchange When ExchangeAsync is called on a rate with timingType=await , the cost is consumed immediately and the reward is held in an Await object. Get a list of Awaits Receiving the reward of an Await after the wait time has elapsed Receive the reward from an Await whose wait time has elapsed. The receive process issues a transaction, and the reward-granting processes defined in acquireActions are executed against other microservices. Deleting an Await (cancellation) Discards a pending Await and cancels the exchange. Note that resources consumed as cost are not returned. If a refund is necessary, compensate via a server-side script using transaction actions. Skipping wait time To skip the wait time by paying an additional cost, configure the cost required to skip via skipByConfig , then call the server-side API (via GS2-JobQueue or GS2-Script). The skip process can also be used as a transaction action, so it can be combined with shop designs such as skip items or skip tickets. Executing a cost-increasing exchange Transaction Actions GS2-Exchange provides the following transaction actions: Consume action: Delete an in-progress exchange wait (Await) Acquire action: Immediately execute an exchange (Exchange), execute a cost-increasing exchange (IncrementalExchange), create an exchange wait (Await), forcibly acquire a pending reward, skip wait time By using “Forcibly acquire pending reward” as an acquire action, you can immediately complete an in-progress construction or expedition (asynchronous exchange) as a reward for acquiring a specific item or achieving a mission. Also, by using “Delete exchange wait” as a consume action, you can interrupt (cancel) an in-progress process. Detailed Reference Reference of GS2-Exchange","lang":"en","section":"microservices","summary":"In-game resource exchange feature\n","title":"GS2-Exchange","url":"/microservices/exchange/"},{"content":"In Game as a Service, growth elements are indispensable. GS2-Experience provides experience and rank features for implementing a game cycle in which players grow their characters and use those grown characters to take on more challenging content. GS2-Experience has a flexible design that lets you centrally manage not only the level of a single character but also the growth of multiple properties (characters, weapons, parties, guilds, etc.) within a single microservice. Use cases Typical use cases for GS2-Experience are: Managing the level of player characters Managing the level of trainable equipment Managing the rank of guilds or teams Managing the level of titles and battle passes Managing the proficiency of each skill in a skill tree graph LR Player[Player] --\u003e|Add experience| Exp[GS2-Experience] Exp --\u003e|Compute rank| Status[Status] Status --\u003e|Threshold exceeded| RankUp[Rank up] RankUp --\u003e|Grant reward| Inventory[GS2-Inventory] RankUp --\u003e|Update stamina max| Stamina[GS2-Stamina] Rank GS2-Experience automatically calculates rank from the experience value. To do so, you must use master data to define a table of experience values that serve as rank-up thresholds. An Experience Model manages rank-up thresholds, and property IDs with arbitrary values can be hung beneath it. The experience value is managed per property ID, and the rank is determined based on the experience value. Relationship between Experience Models and property IDs graph TD N[Namespace] --\u003e EM1[\"ExperienceModel character_ssr\"] N --\u003e EM2[\"ExperienceModel character_sr\"] N --\u003e EM3[\"ExperienceModel weapon\"] EM1 --\u003e P11[\"propertyId: character-001\"] EM1 --\u003e P12[\"propertyId: character-002\"] EM3 --\u003e P31[\"propertyId: weapon-001\"] EM3 --\u003e P32[\"propertyId: weapon-002\"] For example, cases such as “I want to change the required experience table per character type” or “I want to set different rank caps per individual character” can be addressed by preparing an ExperienceModel per character type and assigning each character’s individual ID as the property ID. Rank Cap A rank can have an upper limit. If experience is gained while at the rank cap, that experience is discarded. The initial rank cap is set in the Experience Model, but can be raised individually per property ID. This makes it possible to implement specifications such as raising the rank cap when performing a limit break. Setting Description defaultExperience Initial experience defaultRankCap Initial rank cap maxRankCap Upper limit of the rank cap ( SetRankCap exceeding this is rejected) rankThreshold Array of experience thresholds required for rank-ups Status information A Status is uniquely determined by the combination of user × ExperienceModel × propertyId, and holds the following information: Attribute Description experienceValue Current experience rankValue Current rank rankCapValue Current rank cap nextRankUpExperienceValue Experience required for the next rank-up By referencing nextRankUpExperienceValue on the client, you can easily display the experience required until the next rank-up or draw a progress bar. Reward addition table The Experience Model allows you to configure acquireActionRates to adjust reward amounts based on rank. In addition to the standard rates , bigRates , which can handle values exceeding int64, can also be defined, enabling precise reward control even in games with severe inflation. This is useful for adjustments such as “grant more high-difficulty quest rewards to higher-rank players”. When reflecting a rank-based multiplier in an acquire action of a quest reward, incorporate “apply rank-based reward multiplier” as a transaction action in the clear reward of GS2-Quest. Script Triggers By setting various scripts on the namespace, you can invoke custom scripts before and after experience changes, rank changes, and rank cap changes. Scripts can be executed synchronously or asynchronously, with asynchronous execution also supporting external processing via GS2-Script or Amazon EventBridge. Main event triggers and script setting names are: changeExperienceScript (completion notification: changeExperienceDone ): before and after experience changes changeRankScript (completion notification: changeRankDone ): before and after rank changes changeRankCapScript (completion notification: changeRankCapDone ): before and after rank cap changes In addition, the following fields can take a script GRN directly, and the corresponding script is invoked when its event occurs. rankCapScriptId : handling on rank cap acquisition overflowExperienceScript : handling of surplus experience (overflow experience) after reaching the rank cap Using overflowExperienceScript , you can automate handling such as converting surplus experience after the rank cap is reached into in-game currency stored in GS2-Inventory. Master data operations Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: ExperienceModel : Rank thresholds and reward addition table Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy or various language CDKs. JSON example of ExperienceModel { \"version\": \"2019-09-04\", \"experienceModels\": [ { \"name\": \"character_ssr\", \"metadata\": \"SSR character\", \"defaultExperience\": 0, \"defaultRankCap\": 50, \"maxRankCap\": 99, \"rankThreshold\": { \"metadata\": \"SSR rank table\", \"values\": [ 100, 300, 600, 1000, 1500 ] }, \"acquireActionRates\": [ { \"name\": \"boost\", \"mode\": \"double\", \"rates\": [1.0, 1.1, 1.2, 1.3, 1.4] } ] } ] } Correction by Buff When integrated with GS2-Buff, buffs can adjust the rankCapValue of a Status and the experienceValue of actions such as AddExperienceByUserId and SubExperienceByUserId . This enables flexible adjustments such as temporarily increasing or decreasing acquisition rates or rank caps during events or campaigns. Typical buff targets are as follows: Type Target Adjustable value Model Status rankCapValue Action AddExperienceByUserId experienceValue Action SubExperienceByUserId experienceValue Action AddRankCapByUserId rankCapValue Transaction Actions GS2-Experience provides the following transaction actions: Verify actions: Verify rank, verify rank cap Consume actions: Subtract experience, subtract rank cap Acquire actions: Add experience, set experience, add rank cap, set rank cap, apply rank-based reward multiplier By using “Add experience” as an acquire action, it is possible to perform processes such as directly increasing a character’s experience and ranking it up as a reward for purchasing an item in a shop or for completing a mission. Also, by setting “Add rank cap” as a reward, you can automatically unlock the level cap upon meeting specific conditions. By using “Verify rank” as a verify action, game specifications such as “a quest that can only be attempted by characters of rank 10 or higher” or “an enhancement material exchangeable only at rank 50 or higher” can be implemented purely through master data configuration. Implementation Example Adding experience Adding experience cannot be handled by the SDK for game engines. Add experience as a clear reward of a GS2-Quest quest or as an enhancement reward of GS2-Enhance. Raising the rank cap Raising the rank cap cannot be handled by the SDK for game engines. Use GS2-Exchange to raise the rank cap as a reward for exchanging enhancement materials or duplicate copies of the same character. Get a list of experience values Retrieves all Status the player holds at once. Useful on home screens or character list screens to display status. Get an experience value Get a list of ExperienceModels Used when the client needs to reference the experience tables required for rank-ups. Get a specific ExperienceModel Obtaining a possession-proof signature When linking with other microservices within GS2, you may be required to provide data that guarantees the rank or experience in GS2-Experience is really correct. For example, suppose GS2-Experience manages a player’s rank and GS2-Stamina determines the maximum stamina value based on that rank. GS2-Stamina requires that the rank be specified together with a possession-proof signature. This way, GS2-Stamina does not need to communicate with GS2-Experience behind the scenes to determine whether the player has really reached that rank. sequenceDiagram participant Player as Player participant Exp as GS2-Experience participant Other as Other Microservice Player-\u003e\u003eExp: GetStatusWithSignature Exp--\u003e\u003ePlayer: Body + Signature Player-\u003e\u003eOther: API + Body + Signature Other-\u003e\u003eOther: Verify signature Other--\u003e\u003ePlayer: Result Detailed Reference Reference of GS2-Experience","lang":"en","section":"microservices","summary":"Experience points and rank features\n","title":"GS2-Experience","url":"/microservices/experience/"},{"content":"It is a common specification to combine the resources you own into a single composition. This is the case when organizing multiple characters into a party, or organizing items such as weapons and armor as an equipment set. GS2-Formation is a microservice that defines “what slots exist”, “what can be attached to each slot”, and “how many of the same type of formation can be held” as master data, and manages each player’s formation contents. Terminology graph LR MoldModel --\u003e FormModel FormModel --\u003e SlotModel PropertyFormModel --\u003e SlotModel2[SlotModel] Mold --\u003e Form Form --\u003e Slot PropertyForm --\u003e Slot2[Slot] Term Description MoldModel A type for holding multiple instances of the same kind of formation (parties, equipment sets, etc.). It has the concept of capacity (storage slots) FormModel The configuration definition of a Form associated with a Mold. Defines what slots it has PropertyFormModel A standalone formation definition referenced by property ID. Used in a form where one character has one formation, without going through Mold SlotModel Slot definition. The properties that can be attached to a slot can be restricted with a regular expression Mold The Mold instance per player. Has a capacity and can create Forms up to the maximum capacity Form A formation instance within a Mold. Identified by index PropertyForm A formation instance per property ID Slot Holds the resource actually attached by the player Forms To implement character equipment functionality, you can prepare multiple slots such as weapons, helmets, gauntlets, torsos, legs, and feet, and configure settings so that only items compatible with each slot can be equipped. In Form Model, the types of slots that exist and the types of items that can be organized into each slot are defined as master data. Choosing between Mold and PropertyForm flowchart LR subgraph Mold M1[\"Form #0\"] M2[\"Form #1\"] M3[\"Form #2 (empty)\"] end subgraph PropertyForm P1[\"Formation of character-001\"] P2[\"Formation of character-002\"] end Use Mold when: you want to manage a set of formations (such as Party 1 to N) by number ( index ) and expand the maximum number held ( capacity ) as a growth element Use PropertyForm when: the formation is tied 1:1 to an external resource ID ( propertyId ), such as per-character or per-equipment-set The MoldModel of Mold has initialMaxCapacity (initial capacity) and maxCapacity (expansion upper limit), allowing capacity to be increased or decreased according to player growth or monetization strategies. Targets that can be attached to slots The following resources can be attached to a Slot of a Form / PropertyForm. When attaching, the “proof-of-ownership signature” issued by GS2 is passed as SlotWithSignature . propertyType Attachment Target gs2_inventory ItemSet managed by GS2-Inventory gs2_simple_inventory SimpleItem managed by GS2-Inventory (Simple) gs2_dictionary Entry managed by GS2-Dictionary By setting a regular expression in the slot model’s ( SlotModel ) propertyRegex , you can restrict which property IDs can be attached to a specific slot. For example, you can implement a restriction such as “only Items matching weapon-* can be attached to the weapon slot”. Managing master data By registering master data, you can configure the data and behavior available to the microservice. The types of master data are as follows: MoldModel : Mold storage slot configuration FormModel : Slot configuration of Forms under a Mold PropertyFormModel : PropertyForm slot configuration Example JSON of master data { \"version\": \"2019-09-09\", \"moldModels\": [ { \"name\": \"party\", \"metadata\": \"Party formation\", \"initialMaxCapacity\": 3, \"maxCapacity\": 10, \"formModel\": { \"name\": \"party\", \"slots\": [ { \"name\": \"leader\", \"propertyRegex\": \"character-.*\" }, { \"name\": \"member-1\", \"propertyRegex\": \"character-.*\" }, { \"name\": \"member-2\", \"propertyRegex\": \"character-.*\" } ] } } ], \"propertyFormModels\": [ { \"name\": \"equipment\", \"metadata\": \"Character equipment\", \"slots\": [ { \"name\": \"weapon\", \"propertyRegex\": \"weapon-.*\" }, { \"name\": \"armor\", \"propertyRegex\": \"armor-.*\" } ] } ] } Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Script Triggers Setting updateMoldScript updateFormScript updatePropertyFormScript in the namespace allows custom scripts to be executed before and after formation data updates. Scripts support both synchronous and asynchronous execution, with asynchronous execution supporting external integration via GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: updateMoldScript (completion notification: updateMoldDone ): before and after Mold updates updateFormScript (completion notification: updateFormDone ): before and after Form updates updatePropertyFormScript (completion notification: updatePropertyFormDone ): before and after PropertyForm updates Transaction Actions GS2-Formation provides the following transaction actions: Verify Action: Verify capacity (maximum storage quantity) Consume Action: Subtract capacity Acquire Action: Add capacity, set capacity, set formation contents (Form / PropertyForm), apply acquire actions to organized resources By using “Apply acquire actions to organized resources” as an acquire action, it is possible to perform processes such as directly adding experience points to a character organized in a specific party slot. Additionally, by setting “Add capacity” as a reward, it is possible to automatically expand formation slots upon achieving a specific mission. Implementation example Persisting formation in Mold Form Slots can register ItemSets/SimpleItems managed by GS2-Inventory or Entries managed by GS2-Dictionary. To set either of these, a proof-of-ownership signature must be added. See the description of each service for information on how to obtain a proof-of-ownership signature. propertyType Types gs2_inventory – Attach an ItemSet managed by GS2-Inventory gs2_simple_inventory – Attach a SimpleItem managed by GS2-Inventory gs2_dictionary – Attach an Entry managed by GS2-Dictionary Increasing Mold Capacity Capacity (maximum storage quantity) cannot be increased directly via the SDK for game engines. Allowing client-driven capacity manipulation would expose the value to tampering, so the design intentionally requires capacity changes to be performed through transaction actions. Use GS2-Exchange to increase capacity as a reward, such as through exchange with premium currency. By configuring the Formation capacity-add action in the acquireActions of GS2-Exchange, capacity expansion can be realized as an extension of granting paid items or mission rewards. Get Mold information Get information about a single Mold (current capacity). Get a list of formation contents in Mold Get formation content in Mold Deleting a Form Delete formation contents that are no longer needed. The Mold capacity itself is preserved, and the slot at index becomes reusable as an empty slot. Persisting formation in Property Form Form Slots can register ItemSets managed by GS2-Inventory or Entries managed by GS2-Dictionary. To set either of these, a proof-of-ownership signature must be added. See the description of each service for information on how to obtain a proof-of-ownership signature. Get formation content in Property Form Deleting a Property Form Obtain a signature for formation information When you want to pass the contents of a Form / PropertyForm to another system in a form that guarantees it has not been tampered with, you can obtain signed formation information. This can be used, for example, in a use case that sends the formation contents to the server at the start of a battle. Resource Management and Notes Specifying Properties Properties to be placed in formation slots are specified by property ID. By setting a regular expression for property IDs in the slot model’s propertyRegex , you can restrict which values can be assigned to that slot. Proof-of-Ownership Signatures and Post-Formation Caveats When setting items managed by GS2-Inventory to a slot, you can specify the formation target using a signed item set (proof-of-ownership signature) issued by GS2-Inventory. The ownership guarantee provided by the signed item set is valid only at the time of composition. If the item is subsequently sold or consumed, the formation data remains unchanged. Therefore, when consuming or selling an item in GS2-Inventory, you must first verify — in the client or a script — that the item is not currently in use in a GS2-Formation slot. Preventing Deletion of Items in Formation via ItemSet.referenceOf When using Standard Inventory (GS2-Inventory), you can prevent accidental consumption or deletion of items that are currently in formation by using the referenceOf field on ItemSet . When placing an item into a formation slot, set a string that identifies the slot (e.g., a GRN) in ItemSet.referenceOf . The Inventory Model settings in Standard Inventory include an option to “prohibit consumption when referenceOf is set” . When this option is enabled, any item whose ItemSet.referenceOf is non-empty cannot be consumed or sold, effectively locking the item at the system level while it is in use in a formation. Detailed Reference Reference of GS2-Formation","lang":"en","section":"microservices","summary":"Party and equipment formation feature\n","title":"GS2-Formation","url":"/microservices/formation/"},{"content":"GS2-Freeze is a feature that allows you to freeze the version of GS2 microservices used by your game at an arbitrary time, and to update the version on a schedule managed by the operator. Normally, GS2 microservices are continuously upgraded, and games always use the latest version of the API. While most titles operate without issue under this model, there are situations such as right after the release of a large-scale title, or when stability is to be prioritized for a long period of time, where the operator wants to control the timing of service-side updates. GS2-Freeze is an enterprise feature designed to meet such needs. Tip GS2-Freeze is an enterprise feature and is not broadly provided to all customers. If you would like to use it, please contact support. Stage The central concept of GS2-Freeze is the “Stage”. A stage represents “a set of GS2 microservice versions frozen at a specific point in time”. The following information is associated with each stage. Stage name (name): A name that uniquely identifies the stage Source stage name (sourceStageName): The name of the stage from which version information is sourced Sort number (sortNumber): A number representing the order of stages such as development, verification, and production Status (status): The state of the stage (promoting, rolling back, etc.) By specifying the stage to use when calling GS2 APIs, the game client and server can use the version of the microservices frozen on that stage. graph LR Latest[\"Latest GS2 Microservices\"] -- Promote --\u003e StageDev[\"Stage: dev\"] StageDev -- Promote --\u003e StageStg[\"Stage: staging\"] StageStg -- Promote --\u003e StageProd[\"Stage: production\"] Game[\"Game Client\"] -- API Request --\u003e StageProd Promote / Rollback The operation of updating the version of a stage is called “Promote”. When promote is executed, the version frozen on the source stage is copied to the target stage. For example, “promoting the version of the staging stage to the production stage” reflects a verified version to production. If a problem is discovered after promotion, you can execute a “Rollback” to revert to the previous version. Promote and rollback can take time, and are executed asynchronously internally. The progress of the operation is recorded as Output, and the state can be checked later. Sort order of stages By using sortNumber , you can arrange multiple stages in a hierarchy such as “development”, “staging”, and “production”. The sort order is used as a hint for the display order on the management console and for selecting promotion targets. Transaction Actions GS2-Freeze does not provide transaction actions. Master Data Management Because stages themselves are operational configuration information in GS2-Freeze, the typical “import / export of master data” found in other microservices is not provided. Stage creation, update, and deletion are performed via the management console or GS2-Deploy. Example Implementation GS2-Freeze is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Operations such as stage creation, promotion, and rollback are not intended to be called directly from the game client; we recommend operating via one of the following means. Management console GS2 CLI General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) Template management via GS2-Deploy For details on each SDK, see the corresponding reference page. More practical information Three-stage operation: development, verification, and production A representative usage pattern is to prepare three stages for development, verification, and production, and promote them in order from left to right. Development stage (dev): Uses the latest GS2 microservices to verify new features. Verification stage (staging): Promotes versions that have been verified on the development stage, and performs QA and rehearsals. Production stage (production): After confirming quality on the verification stage, promotes the version and serves it to game players. With this operation, even if a new GS2 release is made, you can reflect it in production only at the timing desired by the game operator. Immediate rollback when issues occur If a defect is found after promoting to the production stage, you can execute rollback to immediately revert to the previous version. Because you can revert just the service-side version without making changes to the game itself, it is useful as an option for emergency response. Detailed Reference Reference of GS2-Freeze","lang":"en","section":"microservices","summary":"Enterprise feature for fixing the version of GS2 microservices\n","title":"GS2-Freeze","url":"/microservices/freeze/"},{"content":"Provides the ability to create a game-specific social graph. While social graphs are a feature that platforms also offer, there is also value in creating your own in-game social graph. Players tend to be reluctant to register platform-wide friend relationships. This is because there is a case of “I want to play the game I’m playing with this person, but I don’t want to play other games with them”. If we treat the social graph provided by the platform as reflecting a relationship closer to real life, and the game-specific social graph as reflecting a relationship within that game, players will feel more comfortable using the friend feature. Friends In order to become friends, a mutual, consensual relationship is required. A friend relationship is established when one of the players who wishes to become a friend sends a friend request to the other player, and the player who receives the friend request accepts it. Follow A follow can be established without the consent of the other party. The person being followed has no way of knowing who is following them as a list. This specification may seem strange when you imagine the specifications of a social network follow. However, we have looked at the specifications of many games that implement the follow feature in-game and found that it is not necessary. If a player who follows you goes on an adventure with your ghost character, it is sufficient to share the rewards obtained from the adventure, and there is little interest in knowing who accompanied you. You cannot get a list, but when delivering a reward message to GS2-Inbox to share rewards earned from an adventure, it is possible to convey profiles by including the user IDs of the players who adventured together in the message payload. Profile GS2-Friend provides an area to hold a player’s profile. The profile can have any value and there are three areas. “Public Profile”, which can be freely viewed by other players. “Follower Profile”, which can be viewed by players who follow the player. “Friend Profile”, which can be viewed by friends. Each of these can be used for different purposes. Blacklist After playing a game for a long time, there may be players who make you feel uncomfortable. This feature allows you to create a list of such players and make it permanent. It is only a persistent feature, and simply adding them here does not perform any function. It is necessary to pass the list to GS2-Matchmaking’s matchmaking conditions, or use the list recorded here separately as needed. Script Triggers Setting followScript unfollowScript sendRequestScript cancelRequestScript acceptRequestScript rejectRequestScript deleteFriendScript updateProfileScript in the namespace allows custom scripts to be executed before and after each operation such as follows, friend requests, and profile updates. Scripts support both synchronous and asynchronous execution, with asynchronous processing enabling external integration through GS2-Script or Amazon EventBridge. These settings can be templated and managed with GS2-Deploy or language-specific CDKs. Main event triggers and script setting names are: followScript (completion notification: followDone ): before and after follows unfollowScript (completion notification: unfollowDone ): before and after unfollows sendRequestScript (completion notification: sendRequestDone ): before and after sending friend requests cancelRequestScript (completion notification: cancelRequestDone ): before and after canceling friend requests acceptRequestScript (completion notification: acceptRequestDone ): before and after accepting friend requests rejectRequestScript (completion notification: rejectRequestDone ): before and after rejecting friend requests deleteFriendScript (completion notification: deleteFriendDone ): before and after deleting friends updateProfileScript (completion notification: updateProfileDone ): before and after profile updates Push Notifications The main push notifications and their configuration names are as follows: followNotification : Notifies when followed receiveRequestNotification : Notifies when a friend request is received cancelRequestNotification : Notifies when a friend request is canceled acceptRequestNotification : Notifies when a friend request is accepted rejectRequestNotification : Notifies when a friend request is rejected deleteFriendNotification : Notifies when a friend is deleted All notifications can be sent via GS2-Gateway and can be forwarded to offline devices as mobile push notifications. Transaction Actions GS2-Friend provides the following transaction actions: Acquire Action: Updating Profile By using “Updating Profile” as an acquire action, it is possible to integrate profile updates into a series of transactions, such as changing a player name by consuming in-game currency. Example implementation Updating Profile Get own profile Get someone else’s public profile Send a friend request Get a list of friend requests you have sent Get a list of received friend requests Accept a friend request Reject a friend request Get a list of friends Delete a friend Follow a player Get a list of followers Unfollow a player Register to blacklist Unregister from blacklist Get a list of blacklisted players Capacity Limits The maximum number of friends and followers is 1,000 each. Additional restrictions may be added depending on the policies of each service you are connecting to. Detailed Reference Reference of GS2-Friend","lang":"en","section":"microservices","summary":"Friend/follow feature\n","title":"GS2-Friend","url":"/microservices/friend/"},{"content":"GS2-Gateway provides the ability to maintain a persistent WebSocket connection between the game client and the server, and to deliver notifications from the server at any time. Normal communication with a game server is a request-response model where the server responds to client requests, but GS2-Gateway enables server-initiated notifications (incoming messages, friend requests, guild invitations, etc.) to be delivered to the client in real time. sequenceDiagram participant Client participant Gateway as GS2-Gateway participant Service as Each Microservice Client-\u003e\u003eGateway: WebSocket Connect Client-\u003e\u003eGateway: SetUserId (authenticate) Service-\u003e\u003eGateway: SendNotification Gateway-\u003e\u003eClient: Deliver notification payload Main features Persistent WebSocket connection GS2-Gateway accepts connections from clients using the WebSocket protocol and maintains connection information per user. When a request arrives from another microservice saying “I want to send a notification to this user”, the payload is delivered to the connected client. The main integration sources are as follows. GS2-Inbox: Notification for newly received messages GS2-Friend: Notification for friend requests and approvals GS2-Guild: Guild join requests and notifications of state changes within a guild GS2-Matchmaking: Match completion notification GS2-Distributor: Notifications for automatic transaction execution GS2-JobQueue: Notification when a new job is queued Concurrent connection control In principle, each user within a namespace can hold only one session at a time. When SetUserId is executed with allowConcurrentAccess set to false , if another session is already connected, the new session can detect this as a concurrent connection error. If set to true , the old session is disconnected at the point when a new session connects. By using this feature, you can deter concurrent logins from multiple devices. Combined with the automatic password change feature of GS2-Account, you can more strongly prevent account sharing or access from the old device after a takeover. Firebase Cloud Messaging integration (mobile push notifications) If you want to deliver notifications even when the client is not running (when the WebSocket is not connected), you can use integration with Firebase Cloud Messaging (FCM). By registering the FCM server key (or service account credentials) in advance in firebaseSecret of the namespace and registering each user’s FCM token obtained from their device to GS2-Gateway, the integration is in place. When delivering a notification, GS2-Gateway sends a push notification via FCM using the registered FCM token for users whose WebSocket session does not exist. This allows notifications to be delivered to users even when the app is not running. By enabling enableTransferMobileNotification on a notification entry, you can control on a per-notification basis whether it is transferred to mobile push. WebSocket API configuration The GS2 client SDKs (Unity / Unreal Engine) include a utility that automatically establishes and maintains the GS2-Gateway WebSocket connection. By specifying GatewaySetting at login time, the WebSocket connection and SetUserId call are performed automatically as part of the login flow. The configuration items are as follows. gatewayNamespaceName : The name of the GS2-Gateway namespace to use allowConcurrentAccess : Whether to allow concurrent connections Transaction Actions GS2-Gateway does not provide transaction actions. Master Data Management GS2-Gateway does not have master data. Configuration such as Firebase integration information and log settings is set in the namespace settings. Example Implementation Establishing a WebSocket connection at login By logging in with GatewaySetting specified, the SDK automatically establishes a WebSocket session and calls SetUserId to associate the user ID. Explicitly setting the user ID If you want to associate the user ID with an already-connected WebSocket session, or if you want to change the concurrent access setting after login, call SetUserId . More practical information Handling concurrent connection disconnects While connected with the setting allowConcurrentAccess: false , if the same user logs in from another device, the current WebSocket session is disconnected. The client needs to detect the disconnection event and take appropriate action, such as navigating to a re-login screen or displaying a message like “You have been logged in from another device”. This effectively allows you to prohibit concurrent play from multiple devices. Disconnecting all players on a version update By combining with GS2-Version, when a new version is released you can disconnect all players’ WebSocket sessions, forcing them to pass the version check at reconnection time. For details, see “Version Update Operating Procedures” in GS2-Version . Detailed Reference Reference of GS2-Gateway","lang":"en","section":"microservices","summary":"WebSocket notification feature\n","title":"GS2-Gateway","url":"/microservices/gateway/"},{"content":"A common specification for character and equipment development is to provide grade-up in addition to level-up as a short-term growth goal. Grading up can raise the level cap and make it possible to develop characters and equipment more powerfully. There are several possible methods of upgrading: some can be done by consuming growth materials, while others involve synthesizing characters or equipment of the same kind. GS2-Grade does not care about the method. Its purpose is to make the operation of GS2-Experience’s level cap simpler to implement by setting a level cap for each grade. graph LR Player[\"Player's possessions\"] -- Grade Up --\u003e Grade[\"GS2-Grade (grade value increases)\"] Grade -- ApplyRankCap --\u003e Experience[\"GS2-Experience (rank cap is reflected)\"] Experience -- Gain experience points --\u003e LevelUp[\"Level Up\"] Grades For each grade, you can define the value to be set as the rank cap of GS2-Experience. Grades are managed for each propertyId that uniquely points to a target such as a character or piece of equipment, and are held individually as Status . Field Description gradeName Grade model name propertyId The GRN indicating the resource to which the grade is applied (e.g., a GS2-Inventory ItemSet) gradeValue The current grade value (integer starting from 0) Initial values for a grade You can set the initial grade value depending on whether the property ID matches a regular expression. For example, by starting at grade 3 when the GS2-Inventory ItemModel name begins with SSR, and at grade 2 when it begins with SR, you can change the initial rank cap depending on the type of ItemModel. You declare initial grades by registering multiple pairs of propertyIdRegex and defaultGradeValue in the master data’s defaultGrades . Grade-up material determination In the case of “synthesizing the same kind of character or equipment” as a method of upgrading, a feature is provided to support determining whether the resource being used as material is “the same kind of character or equipment.” This is achieved by using a regular expression to extract parameters from the property ID of the grade, constructing a regular expression, and determining whether the property ID of the resource to be used as material matches. For example, to determine if an ItemSet in GS2-Inventory is from the same kind of ItemModel, set the regular expression as follows: propertyIdRegex: grn:gs2:{region}:{ownerId}:inventory:namespace-0001:user:(.*):inventory:character:item:(.*):.* gradeUpPropertyIdRegex: grn:gs2:{region}:{ownerId}:inventory:namespace-0001:user:$1:inventory:character:item:$2:.* Now use propertyIdRegex to retrieve the “user ID” and the “ItemModel name”. If the user ID is “user-0001”, the name of the ItemModel is “item-0001”, and the name of the ItemSet is “item-set-0001”, then the GRN (property ID) of the ItemSet is: grn:gs2:{region}:{ownerId}:inventory:namespace-0001:user:user-0001:inventory:character:item:item-0001:item-set-0001 and the replaced value of gradeUpPropertyIdRegex becomes: gradeUpPropertyIdRegex: grn:gs2:{region}:{ownerId}:inventory:namespace-0001:user:user-0001:inventory:character:item:item-0001:.* This allows you to express the ability to specify items of the same kind as material. Reward multiplier table The grade model can have acquireActionRates configured to adjust the reward amounts of acquire actions according to the grade. Using this, you can incorporate growth elements such as “higher-grade characters earn more from quest rewards” or “the experience-point multiplier changes per grade”. mode Description double Multiplies by the multiplier set in rates as a floating-point value. Used for standard corrections of item acquisition amounts. big Treats the multiplier set in bigRates as a string value and supports cases dealing with massive rewards such as BigItem of GS2-Inventory, which can handle numbers exceeding int64. By incorporating Gs2Grade:MultiplyAcquireActionsByUserId into the acquire actions of a transaction, you can convert the actions into a list of acquire actions with the multiplier of the specified grade applied. Script Triggers Setting changeGradeScript in the namespace allows custom scripts to be executed before and after grade changes. Triggers support both synchronous and asynchronous execution. Asynchronous processing also supports external integration through GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: changeGradeScript (completion notification: changeGradeDone ): before and after grade changes Transaction Actions GS2-Grade provides the following transaction actions: Type Action Description Verify Gs2Grade:VerifyGradeByUserId Verify the grade value is the specified value Verify Gs2Grade:VerifyGradeUpMaterialByUserId Verify whether a resource is valid as a grade-up material (matches gradeUpPropertyIdRegex ) Consume Gs2Grade:SubGradeByUserId Subtract from the grade Acquire Gs2Grade:AddGradeByUserId Add to the grade Acquire Gs2Grade:AddRankCapByUserId Reflect the rank cap corresponding to the grade into GS2-Experience Acquire Gs2Grade:MultiplyAcquireActionsByUserId Convert into acquire actions with the multiplier from acquireActionRates applied according to the grade By using “Verify grade-up material” as a verify action, you can validate within a transaction whether the material being used for synthesis (another item or character) is actually possessed. This prevents grade-ups from being performed with illegitimate material specifications. Managing master data By registering master data, you can configure the data and behavior available to the microservice. The types of master data are as follows: GradeModel : rank caps and reward amounts per grade Below is an example JSON of master data. { \"version\": \"2022-06-01\", \"gradeModels\": [ { \"name\": \"grade-0001\", \"metadata\": \"Character Grade\", \"experienceModelId\": \"grn:gs2:{region}:{ownerId}:experience:namespace-0001:model:experienceModel-0001\", \"defaultGrades\": [ { \"propertyIdRegex\": \".*:item:SSR.*\", \"defaultGradeValue\": 3 }, { \"propertyIdRegex\": \".*:item:SR.*\", \"defaultGradeValue\": 2 } ], \"gradeEntries\": [ { \"metadata\": \"Grade 0\", \"rankCapValue\": 30 }, { \"metadata\": \"Grade 1\", \"rankCapValue\": 40 }, { \"metadata\": \"Grade 2\", \"rankCapValue\": 50 }, { \"metadata\": \"Grade 3\", \"rankCapValue\": 60 } ], \"acquireActionRates\": [ { \"name\": \"experience\", \"mode\": \"double\", \"rates\": [1.0, 1.2, 1.5, 2.0] } ] } ] } Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Example implementation Grade addition Grade addition cannot be processed by the SDK for game engines. Incorporate the transaction action Gs2Grade:AddGradeByUserId into the consumption of enhancement materials in GS2-Exchange, or as an enhancement reward in GS2-Enhance, to add to a grade. This lets you implement growth elements while keeping server-side consistency and preventing grade-ups from being triggered by unauthorized client operations. Get a list of grades Get the grade Get an individual grade (Status) Get the current grade value for a specific propertyId (character, equipment, etc.). Synchronize rank caps in GS2-Experience When a grade changes, the rank cap reflection in GS2-Experience is performed automatically. However, when the grade model is updated and the rank cap value for a specific grade is changed, you can apply the updated rank cap by explicitly calling the following synchronization API. Detailed Reference Reference of GS2-Grade","lang":"en","section":"microservices","summary":"Grade/rarity feature","title":"GS2-Grade","url":"/microservices/grade/"},{"content":"GS2-Guard provides the ability to protect access to GS2 API endpoints. It allows you to determine the request source by various conditions such as country or region, IP address, anonymous IP, IP of hosting providers, and IPs with bad reputation, and to allow or deny API requests accordingly. It functions as a kind of lightweight WAF (Web Application Firewall) for games, protecting the game server from misuse, cheating, and abusive traffic. GS2-Guard is not a feature used directly from the game client; it is a mechanism for operators to define blocking policies and apply them to APIs of other GS2 microservices. Blocking Policy A BlockingPolicyModel can be configured per namespace in GS2-Guard, where the access control rules are described. By referencing the target GS2-Guard namespace from the namespace of each GS2 microservice, the blocking policy is applied to API requests to that microservice. The main items that can be configured in a blocking policy are as follows. Default restriction (defaultRestriction): Whether to allow or deny API requests by default. Pass services (passServices): List of GS2 service names exempt from the restrictions. Geographic restriction (locationDetection / locations / locationRestriction): Determines the source country / region of the request, and allows or denies specific countries / regions. Anonymous IP restriction (anonymousIpDetection / anonymousIpRestriction): Determines requests from anonymizing services such as Tor exit nodes or VPNs, and allows or denies them. Hosting provider IP restriction (hostingProviderIpDetection / hostingProviderIpRestriction): Determines requests from hosting-origin IPs such as cloud providers, and allows or denies them. Bad reputation IP restriction (reputationIpDetection / reputationIpRestriction): Determines requests from IPs with bad reputation, such as those known to be used as attack relays, and allows or denies them. Individual IP address restriction (ipAddressesDetection / ipAddresses / ipAddressRestriction): Specifies arbitrary IP addresses or CIDR ranges to allow or deny. graph LR Client[\"Game Client\"] -- API Request --\u003e Guard[\"GS2-Guard (Blocking Policy Evaluation)\"] Guard -- Allow --\u003e Microservice[\"Other GS2 Microservice\"] Guard -- Deny --\u003e Block[\"403 / Access Denied\"] Separation of detection and restriction Each detection condition (Detection) takes either “disabled” or “enabled”, and when the detection condition is enabled, the corresponding restriction is applied. This enables phased operation, such as initially performing only detection and recording it to logs, then later enabling actual denial after observing the situation for a while. Default behavior and whitelist / blacklist usage By setting defaultRestriction to “Allow” and combining “Deny” in individual conditions, you can build a blacklist-style policy. Conversely, by setting defaultRestriction to “Deny” and allowing exceptions with passServices or ipAddresses , you can build a whitelist-style policy. Application to other microservices GS2-Guard is not a service to be used by itself; it takes effect only when it is referenced from namespaces of other microservices. By specifying the GS2-Guard namespace in the namespace settings of each microservice, the configured blocking policy is applied to API requests destined for that namespace. By referencing the same GS2-Guard namespace from multiple microservices, access control can be unified across services. Transaction Actions GS2-Guard does not provide transaction actions. Master Data Management GS2-Guard does not use the typical GS2 “master data import/export”; instead, the blocking policy is held as part of the namespace’s own settings. The blocking policy can be configured via the management console, or registered from CI using GS2-Deploy. A YAML example for registering a blocking policy is as follows. blockingPolicy: defaultRestriction: Allow passServices: - account - version locationDetection: Enable locations: - JP locationRestriction: Deny anonymousIpDetection: Enable anonymousIpRestriction: Deny hostingProviderIpDetection: Enable hostingProviderIpRestriction: Deny reputationIpDetection: Enable reputationIpRestriction: Deny ipAddressesDetection: Enable ipAddresses: - 203.0.113.0/24 ipAddressRestriction: Deny Example Implementation GS2-Guard is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Operations such as creating and retrieving namespaces and configuring blocking policies are not intended to be called directly from the game client; we recommend operating via one of the following means. Management console GS2 CLI General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) Template management via GS2-Deploy For details on each SDK, see the corresponding reference page. More practical information Phased policy rollout When introducing a new blocking policy, immediately setting all items to “Deny” can lock out legitimate players unexpectedly. A recommended approach is to first enable detection only, review the impact from the logs, and then gradually switch over to deny settings. Per-service exceptions By using passServices , you can apply exceptions such as not applying the blocking policy to specific GS2 microservices. For example, you can relax strict IP restrictions for login and version check processes, and apply a strict policy only to APIs such as billing and ranking where the impact of fraud is high. Detailed Reference Reference of GS2-Guard","lang":"en","section":"microservices","summary":"Cheat prevention, WAF, and blocking policy feature\n","title":"GS2-Guard","url":"/microservices/guard/"},{"content":"The guild function is a feature that allows multiple players to create a team and work together toward some goal. GS2-Guild is a microservice that manages guild members and the privileges that guild members have. In GS2-Guild, a “guild” is treated as a single player and referred to as a guild user. Guild members are federated to be able to retrieve and update information as guild users, so that guild members can manipulate common properties. For example, suppose there is a guild A with player A player B as members. It is easy to imagine that common information such as player level and stamina would be managed in conjunction with player A and player B . In the same way, it is easy to imagine that properties such as guild level could be managed by associating them with guild A . One of the characteristics of the GS2-Guild philosophy is that there is no clear distinction between Player A Player B and Guild A , and they are all treated as users . Therefore, the properties that a guild has can be managed using microservices that handle all user data in GS2. For example, a guild can have GS2-Experience ranks/experience, or GS2-Stamina stamina, or GS2-SkillTree skill trees. And GS2-Guild has the ability to manage guild members and issue access tokens that allow guild members to call GS2’s API as guild users . In this case, there is an access privilege control function to control more precisely which APIs can be called as a guild user. By using this function, only players with the position of guild master can purchase GS2-Showcase products as a guild user. Guild Model Guild settings are managed via the GuildModel. Set the initial and maximum member counts with defaultMaximumMemberCount and maximumMemberCount . Specify the guild master’s inactivity period with inactivityPeriodDays to enable automatic succession. rejoinCoolTimeMinutes sets the cooldown period for rejoining after leaving. maxConcurrentJoinGuilds and maxConcurrentGuildMasterCount also allow setting limits on the number of guilds a member can join simultaneously and the number of guilds a member can lead. Guild Members Refers to players who belong to a guild Roles An entity that corresponds to the position of a player belonging to a guild, and defines the type of API that can be executed. Up to 10 types of roles can be defined in one guild model. Permission Settings Roles can define policy document of GS2-Identifier. You can call the API within the scope of privileges \u0026\u0026 privileges of the role before it turns into a guild user. In other words, even if you set strong privileges on a role, it will not allow you to call APIs that you could not call when accessing as the original guild user. Example policy document The minimum policy equivalent to a guild master . { \"Version\": \"2016-04-01\", \"Statements\": [ { \"Effect\": \"Allow\", \"Actions\": [ \"Gs2Guild:Describe*\", \"Gs2Guild:Get*\", \"Gs2Guild:AcceptRequest\", \"Gs2Guild:RejectRequest\", \"Gs2Guild:DeleteMember\", \"Gs2Guild:DescribeIgnoreUsers\", \"Gs2Guild:AddIgnoreUser\", \"Gs2Guild:GetIgnoreUser\", \"Gs2Guild:DeleteIgnoreUser\", \"Gs2Gateway:SetUserId\" ], \"Resources\": [\"*\"] } ] } Minimum policy equivalent to guild users { \"Version\": \"2016-04-01\", \"Statements\": [ { \"Effect\": \"Allow\", \"Actions\": [ \"Gs2Guild:Describe*\", \"Gs2Guild:Get*\", \"Gs2Guild:PromoteSeniorMember\", \"Gs2Gateway:SetUserId\" ], \"Resources\": [\"*\"] } ] } Practical Examples Authorizations are defined using the GS2-Identifier policy document format. As a concrete example, let’s say you want to grant administrative privileges for a guild and privileges for guild users to call the GS2-Experience API. { \"Version\": \"2016-04-01\", \"Statements\": [ { \"Effect\": \"Allow\", \"Actions\": [ \"Gs2Guild:Describe*\", \"Gs2Guild:Get*\", \"Gs2Guild:AcceptRequest\", \"Gs2Guild:RejectRequest\", \"Gs2Guild:DeleteMember\", \"Gs2Guild:DescribeIgnoreUsers\", \"Gs2Guild:AddIgnoreUser\", \"Gs2Guild:GetIgnoreUser\", \"Gs2Guild:DeleteIgnoreUser\", \"Gs2Gateway:SetUserId\", \"Gs2Experience:*\" ], \"Resources\": [\"*\"] } ] } The first half, beginning with “Gs2Guild”, declares the APIs that can be executed as a guild user and specifies the APIs necessary for member management. “Gs2Gateway:SetUserId” is the permission setting to receive notifications about guild users. Without this declaration, notifications cannot be received and the application will not be able to know that a guild membership application has been received or that properties related to guild users have changed. The last part “Gs2Experience:*” is the part that grants the authority to call all APIs of GS2-Experience. Now, if we write “Gs2Experience:*” here, you may wonder if it will be possible to call APIs that grant arbitrary experience values to arbitrary players, such as “Gs2Experience:AddExperienceByUserId”. You may be concerned. However, when performing user federation, you cannot gain privileges stronger than those held by the access token prior to federation. Therefore, the “ApplicationAccess” privilege that a typical game player would have originally cannot call “Gs2Experience:AddExperienceByUserId,” so even if the role’s policy document is written so that all APIs can be called, it will not be possible to call “Gs2Experience:AddExperienceByUserId”. If you want to allow only the guild master to buy products as a guild user in GS2-Showcase, you can manage permissions in detail by adding “Gs2Showcase:Buy” only to the role of the guild master. Custom Roles Guild-specific roles. Can be used if you want to let players define any combination of privileges. Number of participants Guilds can set a limit on the number of participants. The maximum number of participants can be raised on a guild-by-guild basis, and can be implemented in such a way that the maximum number of participants is raised as the guild level increases. Participation Policy Each guild can set its own participation policy. You can set “Free Participation” or “Approval Only”. Free Participation You can request to join a guild and if there is a vacancy in the guild, you will be able to join immediately. Approval System You cannot become a guild member immediately after submitting a join request. You can only become a guild member after you are approved by a guild member who has the approval authority. Search for guilds Guild Display Name You can search for guilds by matching the string registered as the guild’s display name. Attribute values Guilds can have up to 5 different attribute values. Attribute values can only be integer values and can be used for guild search conditions. When searching for guilds, the search criteria can be narrowed down to a maximum of 10 different values for each attribute value. Attribute values cannot be narrowed down by a large or small value. If multiple attribute values are specified as search criteria, the search will be performed using an AND decision; there is no way to search using an OR decision. Whether to include guilds that have reached their maximum member capacity in search results If true, guilds with the maximum number of members will be included in the search results. Note that it is still possible to submit a request to join a guild that has reached its maximum number of members. Search Eligibility Only guilds that have been updated in the past 24 hours are included in the search. This is done to minimize the cost of the search while excluding inactive guilds. Guildmasters are encouraged to update their guild information once a day, even if there are no changes. Updates may include member increases/decreases and role assignments. Cooldown for joining a guild If you set a guild join cooldown parameter, you will not be able to request to join another guild until the cooldown time (in minutes) has elapsed after you leave a guild. Joining multiple guilds A player can join multiple guilds simultaneously. If you wish to limit the number of guilds a player can join, please control this in your application. Emergency measures when guild master retires If the sole guildmaster retires without warning, it will be difficult to maintain the guild. We have emergency measures in place in the event of such a situation. Obtain Guild Master’s last active time The GetLastGuildMasterActivity function can be used to obtain the date and time when the player who owns the guild master role last performed an Assume . By checking this date and time, it is possible to determine “who” among guild master role holders last accessed and “when” that last access was. Days to Activate Emergency Action GuildModel allows you to define the number of days you need to wait for an emergency action to take effect. The number of days defined here must elapse from the guild master’s last active time before the emergency action can be taken. Emergency Action Execution Emergency actions can be executed by calling PromoteSeniorMember. Calling this API will promote the oldest guild member with the oldest active time to the new guild master. At this time, the last active time is also updated as if the promoted player was active. This means that this old member will also have to wait an additional period of time if he/she has been inactive for a long time. Guild Master Change Notification GS2-Guild itself does not have a mechanism for notifying about guild master changes. However, a script can be defined to be executed when a guild member’s role is updated, so that guild members can be notified of guild master changes by writing to guild chat or by other additional processing from the script. Script Triggers Setting createGuildScript , updateGuildScript , joinGuildScript , receiveJoinRequestScript , leaveGuildScript , changeRoleScript , and deleteGuildScript in the namespace allows custom scripts to be executed before and after operations such as guild creation, updates, joining, leaving, and role changes. Scripts support both synchronous execution and asynchronous execution via Amazon EventBridge. Main event triggers and script setting names are: createGuildScript (completion notification: createGuildDone ): before and after guild creation updateGuildScript (completion notification: updateGuildDone ): before and after guild information updates joinGuildScript (completion notification: joinGuildDone ): before and after joining a guild receiveJoinRequestScript (completion notification: receiveJoinRequestDone ): before and after receiving join requests leaveGuildScript (completion notification: leaveGuildDone ): before and after leaving a guild changeRoleScript (completion notification: changeRoleDone ): before and after role changes deleteGuildScript (completion notification: deleteGuildDone ): before and after guild deletion Push Notifications The main push notifications and their configuration names are as follows: changeNotification : notifies when guild information changes joinNotification : notifies when a member joins leaveNotification : notifies when a member leaves changeMemberNotification : notifies when member information changes receiveRequestNotification : notifies when a join request is received removeRequestNotification : notifies when a join request is removed All notifications can be sent in real time via GS2-Gateway, and mobile push forwarding to offline devices can also be configured. Transaction Actions GS2-Guild provides the following transaction actions: Verify Actions: Verify member inclusion (whether a specific user is a member), verify maximum member count Consume Actions: Subtract maximum member count Acquire Actions: Add maximum member count, set maximum member count By using “Verify member inclusion” as a verify action, it is possible to integrate restrictions into transactions, such as rewards that only members of a specific guild can receive, or processes that can only be executed if a user is not a member of a specific guild. This allows for safe implementation of guild competition rewards or recruitment campaigns restricted to non-members. Master Data Management Registering master data allows you to configure data and behavior that can be used by the microservice. Available master data types: GuildModel : settings such as member limits and rejoin cooldown RoleModel : roles defining in-guild permissions Master data can be registered through the management console, imported from GitHub, or registered from CI using GS2-Deploy. Example implementation Create a guild Search guilds Send a join request to the guild If the guild’s participation policy is “free to join”, you will immediately become a guild member Get list of join requests sent Withdraw participation request Get game session to access as guild user Get list of received join requests Approve join request Deny join request Detailed Reference Reference of GS2-Guild","lang":"en","section":"microservices","summary":"Guild feature","title":"GS2-Guild","url":"/microservices/guild/"},{"content":"GS2-Identifier is a service that manages credentials for accessing the GS2 management console and GS2 APIs. It issues and manages users associated with a GS2 owner account, the permissions (security policies) granted to each user, and the client ID / client secret actually used to call APIs. GS2-Identifier is a service that is not intended to be called directly from game clients; it is used for operator-side setup, deployment automation, and CI/CD pipelines. IAM-like design GS2-Identifier provides concepts equivalent to IAM (Identity and Access Management) in cloud services. The main elements are as follows. User: An individual operating entity created under a GS2 owner account Security Policy: A policy document that describes the resources and actions that may be operated Attaching a Security Policy: Associates a security policy with a user to grant permissions Client ID / Client Secret: API credentials issued per user graph TD Owner[\"GS2 Owner\"] --\u003e User[\"User\"] User --\u003e|Attach| Policy[\"Security Policy\"] User --\u003e|Issue| Credential[\"Client ID Client Secret\"] Credential --\u003e|Authenticate| API[\"GS2 API\"] Policy --\u003e|Authorize| API Security Policy A security policy is a permission definition written in JSON format. By describing the resource GRNs to allow and the actions to allow (operation identifiers such as Gs2Account:CreateAccount ), it expresses what operations are permitted for users to whom the policy is attached. It is recommended to design appropriate policies for each development and operational phase, and to grant least privilege per user. Client ID / Client Secret The client ID and client secret issued to a user are used as authentication information when calling GS2 APIs. Multiple credentials can be issued per user, and you can use them appropriately for different purposes or devices. The client secret can only be obtained at the time of issuance; after that, it cannot be retrieved from GS2. If it is leaked, delete the credential and reissue it. Phased permission grants in conjunction with GS2-Version In GS2-Identifier, you can require a credential associated with a user to obtain a Project Token issued by GS2-Version as a “guard”. Specifically, you can give only weak permissions (“enough to perform login and version check”) to the client ID / client secret embedded in the application, and design the system so that strongly-privileged credentials issued after a successful version check are used to access the actual game. graph TD App[\"Application-embedded credential (Least privilege)\"] --\u003e|Version check| Version[\"GS2-Version\"] Version --\u003e|Issue Project Token| App App --\u003e|Authenticate with Project Token| Strong[\"Strongly-privileged credential\"] Strong --\u003e|Call game APIs| API[\"GS2 API\"] This flow prevents clients running on old application binaries or on asset versions that are no longer supported from continuing to access the game APIs. For details, see the GS2-Version documentation. Two-Factor Authentication You can enable two-factor authentication for users who log in to the GS2 management console. GS2-Identifier manages the configuration information for two-factor authentication. Transaction Actions GS2-Identifier does not provide transaction actions. Master Data Management GS2-Identifier does not have master data registration. Security policies, users, and credentials are managed directly via the management console, GS2-Deploy, or APIs. Example Implementation GS2-Identifier is a microservice centered on management / server-side APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Management operations for users, security policies, and credentials are expected to be executed from operator-side setup, deployment automation, or CI/CD pipelines, so we recommend operating via one of the following means. GS2 management console (manage users, policies, and credentials via GUI) Define users, policies, and credentials in GS2-Deploy templates and apply them from CI Call management APIs from operator tools using general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) GS2 CLI For details on each SDK, see the corresponding reference page. Obtaining a Project Token As an exception, user login (issuing a Project Token) is sometimes performed on the application side. By calling the Login API with the embedded client ID / client secret and using the obtained Project Token as authentication information for GS2 APIs, you can call APIs within the scope of the security policies associated with the user. The login API should be called using general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) rather than via the game engine SDK Domain. When combined with GS2-Version, you can achieve phased permission grants by issuing the Project Token after the version check. More practical information Separation of permissions per operational phase The kinds and strength of permissions required differ between the development and production phases. Because GS2-Identifier can attach a different security policy to each user, the following account design is possible. Developer user: Read/write only on resources in the development environment Operator user: Read and limited write on resources in the production environment CI user: Permissions necessary to run GS2-Deploy Game client-embedded user: Can only perform login and version check By issuing dedicated credentials per operating entity and operating under the principle of least privilege, you can limit the impact if a credential is ever leaked. Credential rotation To maintain security, we recommend periodically rotating client IDs and client secrets. By following the procedure of issuing a new credential and then deleting the old one, you can switch over without downtime. Detailed Reference Reference of GS2-Identifier","lang":"en","section":"microservices","summary":"Credential management feature\n","title":"GS2-Identifier","url":"/microservices/identifier/"},{"content":"Implements a mechanism that grants rewards based on how long the game has not been played. For smartphone games, a design where “you launch the app after a while and obtain a large amount of rewards” strongly contributes to encouraging players to return. GS2-Idle is a microservice that makes it easy to incorporate such idle rewards. graph LR Start[\"Start waiting\"] --\u003e Idle[\"Idle time elapses\"] Idle --\u003e Prediction[\"Retrieve scheduled rewards\"] Prediction --\u003e Receive[\"Receive rewards\"] Receive --\u003e Start Categories Multiple idle rewards can be provided. Players can have one waiting time per category. Categories can be used as independent idle-reward units, such as “automatic recovery of a character’s stamina”, “automatic mining at a mining site”, or “automatic generation of materials”. Idle time For each category, you can set how many minutes of idle time grants a reward and the initial value of the maximum idle time. The maximum idle time can be raised per player. Whether to reset unused idle time after receiving rewards or carry it over to the next time can be selected via rewardResetMode . rewardResetMode Behavior Reset When the reward is received, the elapsed time is reset to 0. Any remainder time before the next reward timing is discarded. CarryOver When the reward is received, only the already-acquired interval is subtracted from the elapsed time. The remainder time is carried over to the next wait. Idle Reward Define the list of items obtainable after a set idle time has elapsed for idle rewards. Multiple rewards (up to 10) can be set up, such as “experience + items”. In addition, multiple reward lists can be set so that the reward contents can have variations within the waiting time. For example, you can obtain “Experience +10” and “Enhancement Material Lv.1 x 1” for every 10 minutes of waiting. However, at every 60-minute timing, instead of the above rewards, you obtain “Experience +20” and “Enhancement Material Lv.2 x 1”. Let’s consider an example like the above. In this case, you set up a table like the following for the idle rewards. - reward1 reward2 1 Experience +10 Enhancement Material Lv.1 x 1 2 Experience +10 Enhancement Material Lv.1 x 1 3 Experience +10 Enhancement Material Lv.1 x 1 4 Experience +10 Enhancement Material Lv.1 x 1 5 Experience +10 Enhancement Material Lv.1 x 1 6 Experience +20 Enhancement Material Lv.2 x 1 This allows you to change the reward item contents according to the elapsed time. The reward contents loop, so after 2 hours, you will obtain the items “1,2,3,4,5,6,1,2,3,4,5,6”. Random drawings for idle rewards Sometimes you want more randomness in the reward contents. In such cases, set up GS2-Lottery’s lottery process for the rewards. In conventional GS2-Lottery, the result is not determined until the lottery is drawn. However, when using GS2-Idle, a random-number seed is generated at the start of the waiting period. By using this seed for the lottery when calculating rewards, the randomly drawn item contents can be presented to the player even during the waiting period, and the contents remain unchanged. (Changing the GS2-Lottery prize table will break this premise.) Scheduling of waiting time Each category can be associated with a GS2-Schedule event so that idle rewards linked to the event can be implemented. Suppose the event duration is 2023-01-01 00:00 to 2023-02-01 00:00, and the wait begins at 2023-01-31 23:00. In this case, the idle-time count stops at the moment 2023-02-01 00:00 is reached. Therefore, the content will be the same whether you receive the reward at 2023-02-01 01:00 or at 2023-02-01 09:00. If the event has a recurring setting, the idle time is reset when the recurrence count changes. For example, in a recurring event from every Monday 00:00 to Tuesday 00:00, the waiting time is reset at the moment it reaches 00:00 the following Monday, even if you have not received the previous week’s reward. Apart from the waiting-time schedule, you can set a period during which rewards can be received. Outside the receivable period you can still use Prediction to obtain the scheduled reward, but calling the receive API will result in an error. Status Each player holds one Status per category. The Status contains the following information: Field Description idleStartedAt The time at which waiting started idleMinutes The accumulated idle time (in minutes) nextRewardsAt The next reward acquisition timing maximumIdleMinutes The upper limit of idle time applied to this player randomSeed A fixed seed for lotteries combined with GS2-Lottery Example implementation Start of waiting Waiting is started when the waiting-time information is retrieved for the first time. Retrieve the list of statuses (idle information) Check the reward contents Use the Prediction API to check the scheduled rewards before receiving them. This can be used in cases where you want to present in advance to the player something like “if you wait N more minutes, you can obtain these items”. Receiving rewards When a reward is received, the waiting time is reset. Also, any remaining idle time before the next reward timing is reset to 0 (when rewardResetMode is CarryOver , the remainder time is carried over to the next time). Script Triggers Setting overrideAcquireActionsScriptId or receiveScript in the namespace allows custom scripts to be executed before and after reward calculation and reward-receiving processes. Triggers support both synchronous and asynchronous execution. Asynchronous processing also supports external integration through GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: overrideAcquireActionsScriptId : A synchronous script executed during reward calculation. It allows you to dynamically override the reward list. It can be used to swap rewards according to the player’s state. receiveScript (completion notification: receiveDone ): before and after reward receiving. Synchronous execution allows for permitting/denying the receipt or applying multiplier corrections, while asynchronous execution enables external integration via Amazon EventBridge. Transaction Actions GS2-Idle provides the following transaction actions: Type Action Description Consume Gs2Idle:DecreaseMaximumIdleMinutesByUserId Subtract from the maximum idle time Acquire Gs2Idle:IncreaseMaximumIdleMinutesByUserId Add to the maximum idle time Acquire Gs2Idle:SetMaximumIdleMinutesByUserId Set the maximum idle time Acquire Gs2Idle:ReceiveByUserId Receive rewards By using “Add maximum idle time” as an acquire action, it is possible to perform processes such as automatically expanding the upper limit of accumulable idle rewards when a specific item is obtained or when a player’s rank increases. This allows players to accumulate more idle rewards as they grow, contributing to an improved play experience. Adjustment with buffs By using GS2-Buff, you can correct the category model’s acquireActions or the per-player maximumIdleMinutes with buffs, dynamically adjusting the contents of idle rewards and the maximum idle time according to events and campaigns. For example, you can run operations such as “idle rewards are 1.5x on weekends” or “players holding a specific title get +60 minutes of maximum idle time”. Managing master data By registering master data, you can configure the data and behavior available to the microservice. The types of master data are as follows: CategoryModel : settings for idle time and reward tables Below is an example JSON of master data. { \"version\": \"2024-04-25\", \"categoryModels\": [ { \"name\": \"category-0001\", \"metadata\": \"Stamina\", \"rewardIntervalMinutes\": 10, \"defaultMaximumIdleMinutes\": 360, \"rewardResetMode\": \"CarryOver\", \"acquireActions\": [ { \"acquireActions\": [ { \"action\": \"Gs2Experience:AddExperienceByUserId\", \"request\": \"{\\\"experienceValue\\\": 10}\" } ] } ] } ] } Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Detailed Reference Reference of GS2-Idle","lang":"en","section":"microservices","summary":"Idle reward feature\n","title":"GS2-Idle","url":"/microservices/idle/"},{"content":"Implements a mechanism for delivering messages and gifts from the system or operators to players. In games, situations frequently arise where rewards are delivered asynchronously to players, such as “apology distributions”, “login bonuses”, “purchase bonuses”, and “event rewards”. GS2-Inbox provides message queuing, unread/read management, reward attachment, and automatic deletion by expiration date, serving as the present box feature throughout the lifecycle of the game. sequenceDiagram participant Ops as Operator / Server participant Inbox as GS2-Inbox participant Player as Player Ops-\u003e\u003eInbox: Send message (with reward) Inbox--\u003e\u003ePlayer: receiveNotification Player-\u003e\u003eInbox: Get message list Player-\u003e\u003eInbox: Open message (Read) Inbox-\u003e\u003ePlayer: Grant attached reward (transaction) Player-\u003e\u003eInbox: Delete read message Messages Read management Messages have a read status. You can configure whether to keep read messages in the list or remove them from the list. When isAutomaticDeletingEnabled is enabled in the namespace settings, messages are automatically deleted at the timing of being marked as read. You can implement a specification where only unreceived messages remain in the present box list, without any additional server-side implementation. Attach reward Rewards can be attached to messages. Instead of just marking a message as read, the player can receive the reward attached to the message. Since attachable rewards are expressed as acquire actions ( readAcquireActions ) via the GS2 transaction mechanism, you can distribute resources of any microservice such as GS2-Inventory , GS2-Money , or GS2-Experience as rewards. Expiration date Messages can have an expiration date ( expiresAt ). Messages that reach their expiration date are automatically deleted, regardless of whether they are unread or have been read. They are deleted even if the attached reward has not been received. Message lifecycle stateDiagram-v2 [*] --\u003e Unread: Message received Unread --\u003e Read: Open (Read) Unread --\u003e Expired: Expiration Read --\u003e Deleted: Delete Read --\u003e AutoDeleted: isAutomaticDeletingEnabled Read --\u003e Expired: Expiration Deleted --\u003e [*] AutoDeleted --\u003e [*] Expired --\u003e [*] Global Message When you want to distribute the same message to all players rather than to a specific player, use a “global message”. A global message is defined as master data, and when each player calls ReceiveGlobalMessageAsync , any messages they have not yet received are copied into their inbox. Feature Description expiresAt The message expiration date at an absolute time expiresTimeSpan Determines the expiration date as a relative period from receipt (e.g., 3 days from receipt) messageReceptionPeriodEventId Specifies a GS2-Schedule event ID, making the global message receivable only during a specific period { \"version\": \"2018-04-20\", \"globalMessages\": [ { \"name\": \"welcome\", \"metadata\": \"Gift for new users\", \"readAcquireActions\": [ { \"action\": \"Gs2Money:DepositByUserId\", \"request\": \"{\\\"namespaceName\\\":\\\"money-0001\\\",\\\"slot\\\":1,\\\"userId\\\":\\\"#{userId}\\\",\\\"price\\\":0,\\\"count\\\":100}\" } ], \"expiresTimeSpan\": { \"days\": 7 } } ] } The types of master data are as follows: GlobalMessage : Message definition delivered to all players Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Script Triggers Setting receiveMessageScript , readMessageScript , and deleteMessageScript in the namespace allows custom scripts to be executed before and after message reception, opening, and deletion. Scripts support both synchronous and asynchronous execution, with asynchronous execution supporting external integration via GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: receiveMessageScript (completion notification: receiveMessageDone ): before and after message reception readMessageScript (completion notification: readMessageDone ): before and after message opening deleteMessageScript (completion notification: deleteMessageDone ): before and after message deletion Push Notifications The main push notifications and their configuration names are as follows: receiveNotification : notifies when a message is received You can also specify settings to forward notifications to mobile push notifications when the notification device is offline, ensuring reliable delivery. You can implement a delivery strategy without any additional implementation, such as sending instant notifications to players who have a GS2-Gateway WebSocket connection, and automatically sending iOS/Android mobile push notifications to players who are not connected. Transaction Actions GS2-Inbox provides the following transaction actions: Consume Action: Open message, delete message Acquire Action: Send message By using “Send message” as an acquire action, it is possible to directly deliver messages (with items attached) to a player’s present box as a reward for actions like purchasing a product at a shop or completing a quest, all within a single transaction. This allows for flexible control over the timing of reward distribution and makes it easy to handle situations where a player’s inventory is full by temporarily storing rewards in the present box. Example implementation Sending messages Sending messages cannot be directly called from the SDK for the game engine. It is normally executed via server-side scripts or via the “Transaction Actions” mentioned above. For bulk distribution from operators, messages can be sent through the Management Console or GS2-Deploy. To trigger “message send” as a reward or production element in-game, incorporate Gs2Inbox:SendMessageByUserId into the acquireActions of GS2-Exchange or GS2-Quest. Get list of received messages Get list of unread messages only Get a list of only read messages Open a message When a message is opened, it transitions to the Read state, and at the same time, the reward-granting process defined in readAcquireActions is executed as a transaction. When isAutomaticDeletingEnabled is enabled in the namespace settings, the message is deleted simultaneously with opening. Open messages in bulk Opens multiple messages at once and receives their attached rewards as a single transaction. Since the reward-granting process is executed sequentially internally, you can avoid update rate-limit issues that may occur when opening messages with large numbers of identical items attached in parallel. Delete a message Receive global messages If there are global messages you have not yet received, this copies the messages into your own inbox. The timing can be controlled by the game, such as at login or after the title screen finishes loading. Frequently Asked Questions Can I open messages in bulk? Yes. You can use BatchReadAsync to open multiple messages collectively as a single transaction. See Open messages in bulk for details. You can also call individual ReadAsync in parallel, but you should carefully consider whether the reward-granting process may exceed the limits defined by each microservice. For example, GS2-Inventory defines that the held quantity of the same item can be updated no more than three times per second. Reading 10 messages with the same item attached in parallel may exceed this limit. In principle, no results are lost even if this limit is exceeded. However, after calling the read API, the reward-granting process, which runs asynchronously, may take some time to complete. Even in such cases, with BatchReadAsync the operations are executed sequentially internally, so rewards can be received reliably without hitting rate limits. I want to display an unread-count badge for messages You can display the number of unread messages from the list count obtained by MessagesAsync(isRead: false) . By subscribing to the receive notification ( receiveNotification ), the client can re-fetch the list when a new message arrives. Detailed Reference Reference of GS2-Inbox","lang":"en","section":"microservices","summary":"Present box feature\n","title":"GS2-Inbox","url":"/microservices/inbox/"},{"content":"Manage information about the items a player owns. There are three methods for managing items. The first is standard inventory and the second is simple inventory and the third is big inventory. Standard inventory has the following features. Limit inventory capacity Splitting the same item into multiple stacks of a certain quantity Setting an expiration date on items Simple inventory, on the other hand, does not have the features of standard inventory. Instead, it allows you to process the increase or decrease of multiple items at once. By making good use of simple inventory, the number of API calls can be reduced. Like simple inventory, big inventory does not have the functionality that standard inventory has. It is not possible to increase or decrease multiple items at once, as is the case with simple inventory. Instead, it is possible to hold more than a 64-bit integer quantity of items. Standard Inventory Inventory An entity corresponding to a player’s bag. A bag can have a configurable capacity and cannot contain more items than its capacity. Item Items define the type of possessions. The maximum number of items that can be stacked can be specified for an item. For example, if there is an item type called “Potion” and the maximum number of items that can be stacked is 99 You can have up to 99 potions in your inventory with an inventory capacity usage of 1. In addition, the item can have multiple stacks. If an item is set to allow multiple stacks, you can have more than 100 potions in your inventory. For example, if you have 150 potions, two entries will be created: one with 99 potions stacked and one with 51 potions stacked. This takes up 2 inventory slots. If multiple stacks are disabled, you will not be able to have more than 99 potions, and you will be able to discard any additional potions you acquire. Item Expiration Date Items may have an expiration date. Items with an expiration date are automatically removed from your inventory after the expiration date. Items with an expiration date create a separate stack for each expiration date, and each stack takes up inventory space. Therefore, if you place items with expiration dates on items that cannot have multiple stacks, they will be discarded except for the first item with an expiration date that you purchased (or the first item without an expiration date that you purchased). Item Sets To manage multiple stacks of an item type, An Item Set represents a specific stack of an item, allowing multiple stacks of the same item type to be distinguished. This entity has a stack-specific ID for each stack, in addition to the ID representing the item type. With this stack-specific ID, it is possible to clearly distinguish stacks of “Potion x 99” from stacks of “Potion x 51”. Reference Of “Reference Of” information can be added to an Item Set. This is used to indicate that a specific item is being used by another entity (e.g., character equipment, party organization, listing in a market, etc.). An Item Set with one or more references cannot be consumed or deleted, even if the quantity is sufficient. This prevents system-level errors such as accidentally selling an equipped item or using it as enhancement material. When consuming a potion, the stack-specific ID can be used in addition to the item ID to indicate which stack the potion is being consumed from. The stack-specific ID can be omitted, in which case the lowest stack will be used first. Simple Inventory Simple Inventory It is an entity that corresponds to a bag owned by a player. It is an entity that binds multiple simple items and has no specific properties in the simple inventory. Simple Item An item defines the type of possession. Big Inventory Big Inventory It is an entity equivalent to a player’s bag. It is an entity that binds multiple big items and has no specific properties in the big inventory. Big Item An item defines the type of possession. Script Triggers By configuring acquireScript , overflowScript , consumeScript , simpleItemAcquireScript , simpleItemConsumeScript , bigItemAcquireScript , and bigItemConsumeScript in the namespace, you can invoke custom scripts before and after item acquisition and consumption. Scripts can be executed synchronously or asynchronously. Asynchronous execution supports external processing via GS2-Script or Amazon EventBridge. The main configurable event triggers and script setting names are as follows: acquireScript (Completion notification: acquireDone ): Before and after standard item acquisition overflowScript (Completion notification: overflowDone ): Before and after capacity overflow consumeScript (Completion notification: consumeDone ): Before and after standard item consumption simpleItemAcquireScript (Completion notification: simpleItemAcquireDone ): Before and after simple item acquisition simpleItemConsumeScript (Completion notification: simpleItemConsumeDone ): Before and after simple item consumption bigItemAcquireScript (Completion notification: bigItemAcquireDone ): Before and after big item acquisition bigItemConsumeScript (Completion notification: bigItemConsumeDone ): Before and after big item consumption Master Data Operations Registering master data allows you to configure data and behaviors available to microservices. Master data types include the following: InventoryModel : Defines inventory capacity and types ItemModel : Defines stack limits and expiration dates Master data can be registered via the management console. Additionally, you can set up workflows to reflect data from GitHub or register via CI using GS2-Deploy. Buff-Based Adjustments When integrated with GS2-Buff, buffs can adjust the inventory’s currentInventoryMaxCapacity and the acquisition/consumption amounts for AcquireItemSetByUserId , ConsumeItemSetByUserId , AcquireSimpleItemsByUserId , ConsumeSimpleItemsByUserId , AcquireBigItemByUserId , and ConsumeBigItemByUserId . This enables flexible adjustments to capacity and acquisition/consumption amounts for events and campaigns. Transaction Actions GS2-Inventory provides the following transaction actions: Standard Inventory Verify Actions: Verify inventory maximum capacity, verify item count, verify “reference of” Consume Actions: Consume item set Acquire Actions: Add/Set capacity, acquire item set (including with specific grade), add/delete “reference of” By using “add/delete reference of” as an acquire action, you can safely perform equipment changes or organization updates within a transaction while simultaneously toggling the protection status of items. Simple Inventory Verify Actions: Verify simple item count Consume Actions: Consume simple items Acquire Actions: Acquire/Set simple items Big Inventory Verify Actions: Verify big item count Consume Actions: Consume big item Acquire Actions: Acquire/Set big item Example implementation Obtaining items The acquisition of items cannot be handled by the SDK for the game engine. Consuming items It is not recommended to use this API to process item consumption. It is recommended to use GS2-Exchange / GS2-Showcase / GS2-Quest services to perform some kind of processing instead of consuming items. Standard Simple Big Get inventory information Standard Simple Simple Inventory does not have this feature. Big Big Inventory does not have this feature. Get a list of items in inventory Standard Simple Big Expanding inventory capacity Expanding inventory capacity cannot be handled by the SDK for game engines. Obtaining a Possession Certificate Signature When interfacing with other microservices in GS2, you may be asked for data that guarantees that you really own the item in GS2-Inventory. For example, let’s say that GS2-Inventory manages character possession state and GS2-Formation manages party formation state. When setting up party members in GS2-Formation, you would make an API request to set up a character named “character-0001,” but GS2-Formation will request that you specify “character-0001” in conjunction with a proof-of-possession signature. This eliminates the need for GS2-Formation to communicate with GS2-Inventory behind the scenes to determine if the character is really owned. Standard Simple Big Big Inventory does not have this feature. Item Consumption Order by Expiration Date When consuming items that have expiration dates, if you do not explicitly specify which item set to consume from, items are consumed starting from the item set closest to its expiration date. This ensures that items nearing expiration are used first automatically. Detailed Reference Reference of GS2-Inventory","lang":"en","section":"microservices","summary":"Personal belongings management feature","title":"GS2-Inventory","url":"/microservices/inventory/"},{"content":"GS2-JobQueue provides a job queue feature for stacking up processes to be executed asynchronously on the game server. Game processing includes operations that do not need to return a result immediately, and operations that should progress gradually over time on the server side. Such processing can be registered as a “job” in the queue, and executed later either at the timing when the player accesses the server or by an explicit API call. Main use cases An execution platform for running GS2-Script asynchronously Splitting long-running processing into smaller steps, registering each step as a job, and processing them sequentially Issuing and executing transactions in batches on the server side for rewards distributed during login As a completion notification handler for other microservices, performing follow-up processing asynchronously graph LR Producer[\"Job producer (Other microservices / GS2-Script)\"] --\u003e Queue[\"GS2-JobQueue\"] Queue --\u003e Run[\"Player calls Run or auto execution\"] Run --\u003e Script[\"GS2-Script\"] Script -- Success --\u003e Result[\"Recorded as JobResult\"] Script -- Failure --\u003e Retry{\"Max attempts reached?\"} Retry -- No --\u003e Queue Retry -- Yes --\u003e DeadLetter[\"Stored as DeadLetterJob\"] Auto run mode If enableAutoRun is enabled in the namespace settings, jobs queued for a user are automatically executed at the end of each microservice’s API processing. Jobs queued on the server side are consumed sequentially just by the player operating the app. If enableAutoRun is disabled, the client must explicitly call the Run API to execute jobs. Job result The execution result of a job is recorded as a JobResult per attempt number ( tryNumber ). A JobResult includes the GS2-Script exit code, execution log, and result payload, allowing you to review the execution history later. Notification settings By configuring runNotification and pushNotification in the namespace settings, you can notify the client via GS2-Gateway when a job has been executed, or when a new job has been queued. You can use this notification as a hook to perform further actions on the client, such as re-fetching the remaining information. Transaction Actions GS2-JobQueue is often called as the destination of completion notifications from other microservices, and provides job registration as a transaction action. Acquire Action: Register a job in the user’s queue For example, a configuration is possible where GS2-Mission completion rewards push jobs into GS2-JobQueue, and GS2-Script is executed in batches later. Master Data Management GS2-JobQueue does not have master data. Its behavior is controlled only by the namespace settings. Example Implementation Run jobs in your queue Called when enableAutoRun is disabled, or when you want to explicitly progress job consumption. Calling Run takes one job from the queue, executes GS2-Script, and returns the result. If IsLastJob is true , it indicates that no more jobs remain to be consumed. Get a job execution result Retrieve the execution result of a specific attempt of a specific job. Get the state of a job Retrieve the latest state of a job queued in the queue. You can check information such as the current attempt count and the GS2-Script registered with the job. Detailed Reference Reference of GS2-JobQueue","lang":"en","section":"microservices","summary":"Asynchronous job queue\n","title":"GS2-JobQueue","url":"/microservices/job_queue/"},{"content":"GS2-Key is a service that manages encryption keys (symmetric keys) used within GS2, and provides AES-based encryption and decryption APIs. In addition to use cases such as server-side encryption and decryption of sensitive data, it is also used as the key management foundation for various signing and encryption processes used internally by GS2 itself. Encryption key management In GS2-Key, encryption keys are created and managed under a namespace. A key can hold the following information. Key name Description (description: used for operational identification, such as the purpose or description) The actual secret key (the secret) used for encryption is securely generated by GS2 at the time of key creation and stored within GS2 itself. The design does not allow the secret key itself to be retrieved to the client side; rather, encryption and decryption requests are sent to GS2-Key and only the result is returned. graph TD App[\"Application\"] --\u003e|Encrypt(plaintext)| Key[\"GS2-Key\"] Key --\u003e|Ciphertext| App App --\u003e|Store on server or send| Storage[\"Datastore\"] Storage --\u003e|Ciphertext| App2[\"Application\"] App2 --\u003e|Decrypt(ciphertext)| Key Key --\u003e|Plaintext| App2 Use cases Internal use within GS2 Microservices that handle sensitive data internally, such as GS2-Account’s password signing or GS2-Auth’s token issuance, use keys managed by GS2-Key. By specifying a key when creating the namespace of each microservice, it is used for the encryption processing needed within that namespace. Encrypting application-specific data When your application handles sensitive information independently, you can also directly call the GS2-Key Encrypt / Decrypt APIs to perform encryption and decryption. This achieves server-side encryption without embedding the secret key in the application. This is useful in cases where you want to safely manage highly confidential configuration values or authentication information for external services on the GS2 side. Transaction Actions GS2-Key does not provide transaction actions. Master Data Management GS2-Key does not have master data registration. Keys are created and managed via the management console, GS2-Deploy, or API. Example Implementation GS2-Key is a microservice centered on management / server-side APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Key creation and Encrypt / Decrypt calls are mainly used by being referenced from GS2 internal microservices, or by being called from the server side via GS2-Script. When calling the API directly, we recommend operating via one of the following means. Management console (key creation and management) Template management via GS2-Deploy (managing keys as code) Calling from GS2-Script (using Encrypt / Decrypt within server-side logic) Calling from the backend server using general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) GS2 CLI For details on each SDK, see the corresponding reference page. More practical information Key rotation When you want to periodically rotate encryption keys according to a security policy, you can create a new key and switch subsequent encryption processing to the new key. The old key should not be deleted immediately since it is needed for decryption; we recommend keeping it until the migration of ciphertexts is complete. Managing GitHub API keys In addition to encryption keys, GS2-Key can store API keys used when fetching master data from GitHub. GS2-Deploy and various microservices that fetch master data can access private repositories by referencing the API key registered here. Detailed Reference Reference of GS2-Key","lang":"en","section":"microservices","summary":"Encryption key management feature\n","title":"GS2-Key","url":"/microservices/key/"},{"content":"This is a mechanism for limiting the number of times a player can act. You can centrally manage frequently-occurring count limits in games, such as “you can draw the gacha up to 5 times a day” or “a reward you can receive only once a week”. graph LR Action[\"Player action\"] --\u003e CountUp[\"Count up (with maxValue specified)\"] CountUp -- Limit not reached --\u003e Success[\"Allow processing\"] CountUp -- Limit reached --\u003e Failure[\"Reject processing\"] Reset[\"Reset cycle\"] --\u003e Counter[\"Reset counter to 0\"] Counter An entity used to represent the number of times a player has acted. The count limit is achieved by a mechanism that specifies the maximum acceptable value when raising the counter and attempting to count up; if the maximum value would be exceeded, the count-up fails, causing subsequent processing to fail as well. A distinctive feature is that there is no maximum value on the counter itself; rather, the maximum is set on each count-up action. For example, consider the process of recovering stamina. In many games, there is a limit to the number of times you can recover your stamina in a day. And the more you recover, the higher the cost required for recovery. Such a specification can be expressed as follows. Tier Cost required to recover Number of times you can perform Tier.1 5 10 Tier.2 10 10 Tier.3 20 10 Tier.4 40 10 And the table below treats this as a count-up action of a count limit and the cost required for recovery. Tier counter name counter increase maximum counter value cost required to recover Tier.1 RecoveryStaminaCounter 1 10 5 Tier.2 RecoveryStaminaCounter 1 20 10 Tier.3 RecoveryStaminaCounter 1 30 20 Tier.4 RecoveryStaminaCounter 1 40 40 The same counter is used for all tiers, and the lower the cost of recovery, the lower the maximum counter value. In this way, you can design things so that the cheapest Tier.1 becomes unavailable first, forcing the purchase of Tier.2; eventually Tier.2 also becomes unavailable, forcing the purchase of Tier.3, and so on. Reset counters Counters can have a reset cycle. There are the following types of reset cycles. resetType Description notReset Does not reset (the count remains permanently unless reset manually) daily Resets daily at resetHour weekly Resets every week on resetDayOfWeek at resetHour monthly Resets every month on resetDayOfMonth at resetHour days Resets every days days starting from the anchor date ( anchorTimestamp ) By using anchorTimestamp , flexible scheduling such as resetting every N days from an event start date is possible. Adjustment with buffs By integrating with GS2-Buff, you can use buffs to adjust the maxValue of CountUp / CountUpByUserId , temporarily increasing or decreasing the upper limit. This is useful when implementing event-based easing measures such as “for a limited time, double the number of gacha pulls allowed per day”. Script Triggers Setting countUpScript in the namespace allows custom scripts to be executed before and after count-up processing. Triggers support both synchronous and asynchronous execution. Asynchronous processing also supports external integration through GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: countUpScript (completion notification: countUpDone ): before and after count-up processing. Transaction Actions GS2-Limit provides the following transaction actions: Type Action Description Verify Gs2Limit:VerifyCounterByUserId Verify the counter value (equal/less than/greater than, etc.) Consume Gs2Limit:CountUpByUserId Add to the counter value (count up) Acquire Gs2Limit:CountDownByUserId Subtract from the counter value (count down) Acquire Gs2Limit:DeleteCounterByUserId Delete the counter (reset) By using “Subtract counter value (count down)” as an acquire action, it is possible to recover the limit count (effectively reverting the consumed count) when a specific item is obtained or as a reward for completing a mission. This makes it easy to design rewards that encourage continued play. Managing master data By registering master data, you can configure the data and behavior available to the microservice. The types of master data are as follows: LimitModel : Reset cycles and upper limits Below is an example JSON of master data. { \"version\": \"2023-09-04\", \"limitModels\": [ { \"name\": \"daily\", \"metadata\": \"Daily limit\", \"resetType\": \"daily\", \"resetHour\": 5 }, { \"name\": \"weekly\", \"metadata\": \"Weekly limit\", \"resetType\": \"weekly\", \"resetDayOfWeek\": \"monday\", \"resetHour\": 5 } ] } Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Example implementation Obtain a list of counters Get counter status Raise the counter value It is not recommended to use this API to count up. It is recommended to set the counter value increase as the cost for executing the process to which you want to apply a count limit, such as GS2-Exchange / GS2-Showcase / GS2-Quest. Attempting a count-up that would exceed maxValue will throw an OverflowException . You can express the count limit by catching this exception on the client and displaying UI such as “You have reached today’s limit”. Force counter reset Forced counter resets cannot be handled by the SDK for game engines. You can reset a counter by calling DeleteCounterByUserId from the game server, or by executing Gs2Limit:DeleteCounterByUserId as an acquire action of a transaction. Detailed Reference Reference of GS2-Limit","lang":"en","section":"microservices","summary":"Number of times limit feature\n","title":"GS2-Limit","url":"/microservices/limit/"},{"content":"GS2-Lock is a distributed mutual exclusion service that provides a mutex operating on a per-resource basis, preventing multiple server processes and multiple execution environments from accessing the same resource simultaneously. In game operations, problems such as “performing the same process twice on the same player” or “different backend servers writing to the same data concurrently” can easily occur. GS2-Lock prevents these problems through a shared mutex provided as a microservice. Mutex basics GS2-Lock acquires locks on a “mutex” resource identified by a combination of “namespace”, “user ID”, and “property ID”. For the property ID, you specify an arbitrary string that uniquely identifies the resource you want to mutually exclude. For example, a usage pattern is to assign a different property ID per process you want to avoid double-executing, such as “gacha drawing process”, “item count update”, or “external integration notification”. graph TD Server1[\"Backend Server A\"] --\u003e|Lock| Mutex[\"GS2-Lock Mutex\"] Server2[\"Backend Server B\"] --\u003e|Wait for Lock| Mutex Mutex --\u003e|Acquired| Server1 Server1 --\u003e|Unlock| Mutex Mutex --\u003e|Acquired| Server2 Transaction ID A transaction ID is specified when acquiring a lock. If the same transaction ID acquires a lock on the same mutex recursively, the reference count is incremented and it behaves as a reentrant lock. The lock is fully released only when Unlock is executed the same number of times. A double acquisition by a different transaction ID becomes a conflict, and the new session waits until the previously holding session releases the lock. Automatic release by TTL A TTL (Time To Live) can be set on a lock, and the lock is automatically released after the TTL elapses. This prevents deadlocks even if the process that acquired the lock abnormally terminates or the lock release call is not made due to a network failure. Set the TTL to an appropriate value based on the maximum expected execution time of the process. Mutual exclusion across multi-title and multiple backends Because GS2-Lock is provided as a GS2 microservice, you can implement common mutual exclusion across multiple titles, multiple backend servers, and multiple regions. You can also call it from GS2-Script to perform mutual exclusion between the internals of server-side scripts and other script executions or external processes. Transaction Actions GS2-Lock does not provide transaction actions. Master Data Management GS2-Lock does not have master data registration. You can start using it just by creating a namespace. Example Implementation GS2-Lock is a microservice centered on management / server-side APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Because it is primarily intended for use within server-side logic in GS2-Script or from your own backend servers, instead of calling it directly from the game client, we recommend operating it via one of the following means. Calling from GS2-Script (mutual exclusion through server-side scripts) Calling from the backend server using general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) Management console (for verification and operations) GS2 CLI For details on each SDK, see the corresponding reference page. More practical information Double-execution prevention pattern In online games, due to unstable networks, players may send the same request multiple times in a short period. If such requests are accepted on the server side, they can lead to issues such as double item granting. By issuing a transaction ID per request and acquiring a lock with a short TTL in GS2-Lock, duplicate processing with the same transaction ID is treated as a reference count, while processing of the same kind received as a different request is rejected as a conflict. Ensuring consistency between backends In scenarios where multiple backend servers write to a common resource, a design that acquires a per-resource mutex in GS2-Lock and then performs read-modify-write is effective. By embedding the resource identifier in the property ID, you can achieve fine-grained mutual exclusion per resource. Detailed Reference Reference of GS2-Lock","lang":"en","section":"microservices","summary":"Distributed mutual exclusion feature\n","title":"GS2-Lock","url":"/microservices/lock/"},{"content":"GS2-Log provides a feature for aggregating and storing API access logs of all Game Server Services microservices embedded in your game. In game operation, it is very important to be able to later trace “when, who, which API was called, with what arguments, and what result was returned”. GS2-Log data can be leveraged as the foundation for various operational tasks such as investigating fraudulent players, checking game balance, handling user inquiries, and aggregating KPIs. GS2-Log features are not intended to be used directly from the game client; they are designed to be used in conjunction with operator-side tools and data analysis platforms. Log types GS2-Log records the following four types of logs. AccessLog A log recorded every time an API of a microservice is called. timestamp : API call time requestId : A unique ID identifying the request service : The microservice name that was called method : The API method name that was called userId : The user ID of the caller request : Request parameters (JSON string) result : Response content (JSON string) This enables fine-grained behavioral tracking at the API level and can be used for defect investigation or behavior log analysis. IssueStampSheetLog A log recorded when a transaction is issued. A transaction is the batch execution unit of acquire and consume actions in Game Server Services. The log records the list of consume actions at the time of issuance and what triggered the issuance. timestamp : Time of issuance transactionId : Transaction ID (identifier per transaction issuance) service : Issuing microservice method : Issuing API userId : User ID action : Acquire action args : Arguments of the action tasks : List of consume actions contained in the transaction ExecuteStampSheetLog / ExecuteStampTaskLog Logs recorded when the entire transaction or each consume action is executed. By combining these with IssueStampSheetLog , you can trace when an issued transaction was executed and how. This information can be leveraged to detect replay attacks, illegal multiple executions, and consistency issues between services. sequenceDiagram participant Client participant ServiceA as Microservice A participant Sheet as Transaction participant ServiceB as Microservice B participant Log as GS2-Log Client-\u003e\u003eServiceA: Reward request ServiceA-\u003e\u003eLog: AccessLog ServiceA-\u003e\u003eSheet: Issue Transaction ServiceA-\u003e\u003eLog: IssueStampSheetLog Sheet-\u003e\u003eServiceB: Execute consume action ServiceB-\u003e\u003eLog: ExecuteStampTaskLog Sheet-\u003e\u003eLog: ExecuteStampSheetLog Log export destinations Logs recorded with GS2-Log can be forwarded to the export destination specified in the namespace settings. type Destination Description gs2 GS2 internal log storage Stored within GS2-Log without export bigquery Google Cloud BigQuery Specify gcpCredentialJson and bigQueryDatasetName firehose Amazon Kinesis Data Firehose Specify awsRegion / awsAccessKeyId / awsSecretAccessKey / firehoseStreamName By writing aggregation queries at the export destination, you can continuously measure custom KPIs such as DAU, billing amounts, and the count of specific item acquisitions. Log retention period By specifying logExpireDays , you can control the retention period of logs within GS2-Log. For logs that require long-term retention, it is recommended to use the export feature above to forward them to your own data warehouse. In-game logs There is also an “in-game log” feature where the client can send arbitrary payloads to GS2-Log. You can send any event that occurs in the game (stage clear, gacha result, UI operations, etc.) as a pair of payload and tags , and handle them on the same aggregation infrastructure as AccessLog. Transaction Actions GS2-Log does not provide transaction actions. Master Data Management GS2-Log does not have master data. Configuration such as the log aggregation destination is set in the namespace settings. Example Implementation GS2-Log is mainly used for aggregation and analysis, and the reference APIs are expected to be called from operator-side tools and dashboards. Only in-game log sending is used from the game client, so a sample via Unity SDK is shown. For aggregation APIs and export settings, operate them via the management console or general-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java). Send an in-game log (Unity) Send a game-internal log with an arbitrary payload and tags. Tags can be used for filtering on BigQuery, etc., so storing event types or stage IDs helps in analysis. The Unreal Engine SDK does not provide an Ez Domain class targeted at the game client. When sending in-game logs from Unreal Engine, call the GS2-Log SendInGameLog API directly via the Source SDK. More practical information Fraud detection using logs By cross-checking IssueStampSheetLog and ExecuteStampSheetLog , you can verify whether issued transactions were executed as expected. If multiple execution logs are recorded for the same transactionId , or if execution logs exist without a matching issuance log, this may indicate replay attacks or a fraudulent client implementation. Log aggregation operations By periodically running aggregation queries against export destinations such as BigQuery, you can obtain the following metrics. Number of daily active users (deduplicated by userId ) Number of API calls per specific microservice or API Frequency of transaction issuance for gacha, purchases, experience gains, etc. Ratio and trends of APIs that returned an error response Detailed Reference Reference of GS2-Log","lang":"en","section":"microservices","summary":"API access log and analysis feature\n","title":"GS2-Log","url":"/microservices/log/"},{"content":"This is a mechanism that distributes rewards to players who log in to the game every day. It provides a generic version of patterns frequently used in operations, such as distributing items that change daily, login bonuses that loop on a 7- or 30-day cycle, and the ability to retroactively compensate for missed days. Mode There are two ways to provide login bonuses: 《Scheduled Mode》 and 《Streaming Mode》. graph LR Mode{Bonus mode} --\u003e Schedule[\"Scheduled Mode (mode: schedule)\"] Mode --\u003e Streaming[\"Streaming Mode (mode: streaming)\"] Schedule -- Fixed to date --\u003e SchEx[\"Day 1=Gold, Day 2=Silver... Missed days are skipped\"] Streaming -- Consumed in order --\u003e StrEx[\"Item 1=Gold, Item 2=Silver... Carries over even if missed\"] Streaming --\u003e Repeat{\"repeat setting\"} Repeat -- enabled --\u003e Loop[\"Restart from the beginning after reaching the end\"] Repeat -- disabled --\u003e Stop[\"Stop at the end\"] Scheduled Mode This mode is used in conjunction with GS2-Schedule events. Define the transaction actions to be distributed as rewards for each schedule date. Rewards change every 24 hours from the event start date and time, and each reward can be received once. Any rewards missed along the way will be skipped. Streaming Mode Streaming mode distributes the transaction actions set as rewards in the stream from the top in order. Even if there is a day you did not receive the reward, it will not be skipped and you will obtain the next reward in the stream. If you associate a GS2-Schedule event with a Streaming Mode login bonus, you will receive the next reward in the stream every 24 hours from the event’s start date and time. If not set, you specify the time in 24-hour increments in the UTC time zone at which the reward type changes. Repeat Streaming-mode login bonuses can be configured to repeat. If the repeat setting ( repeat: enabled ) is enabled, when the end of the stream is reached, the next day reward distribution resumes from the beginning of the stream. By using this feature, a permanent login bonus can be looped every 7 or 30 days. If you select repeat: disabled , once distribution has reached the end of the stream, no further rewards are obtained from that bonus. This can be used for time-limited campaigns. Missed-receive Relief The Missed-receive Relief feature can be used when you miss an item in Scheduled Mode, or when you end up in a state during the event period of Streaming Mode where you cannot obtain all items in the stream. By paying a configured cost, you can obtain the missed items. Missed-receive relief is only available for login bonuses associated with GS2-Schedule events, and only rewards up to the number of days elapsed from the event’s start date can be received. In other words, future login bonuses cannot be received even if the cost is paid. For the missed-receive relief cost, you can set consume actions such as GS2-Money2 in missedReceiveReliefConsumeActions , enabling operations where players spend gems to recover missed days. You can also specify verify actions in missedReceiveReliefVerifyActions as preconditions for receipt. Adjustment with buffs By integrating with GS2-Buff, you can apply buffs to the bonus model’s acquireActions and missedReceiveReliefConsumeActions , dynamically adjusting the reward contents and missed-receive relief costs according to events. For example, you can run operations such as “double login bonuses during the campaign period” or “halve missed-receive relief costs for VIP players”. Script Triggers Setting receiveScript in the namespace allows the receive / receiveDone script hooks to be called before and after the login-bonus receipt process. Scripts support both synchronous and asynchronous execution, with asynchronous execution supporting external integration via GS2-Script or Amazon EventBridge. The main event triggers and script setting names that can be configured are as follows: receiveScript (completion notification: receiveDone ): before and after receiving the login bonus Managing master data By registering master data, you can configure the data and behavior available to the microservice. The types of master data are as follows: BonusModel : Defines daily or streaming reward distribution Master Data Field Description name The bonus model name mode schedule (Scheduled) or streaming (Streaming) periodEventId The associated GS2-Schedule event ID (optional) resetHour UTC hour at which rewards switch in Streaming Mode when no event is associated repeat Loop behavior in Streaming Mode ( enabled / disabled ) rewards A list of acquireActions distributed at each step missedReceiveRelief Whether missed-receive relief is enabled ( enabled / disabled ) missedReceiveReliefVerifyActions Verify actions before executing missed-receive relief missedReceiveReliefConsumeActions Consume actions when executing missed-receive relief Below is an example JSON of master data. { \"version\": \"2020-10-19\", \"bonusModels\": [ { \"name\": \"bonus-0001\", \"metadata\": \"7days\", \"mode\": \"streaming\", \"resetHour\": 15, \"repeat\": \"enabled\", \"rewards\": [ { \"acquireActions\": [ { \"action\": \"Gs2Inventory:AcquireItemSetByUserId\", \"request\": \"...\" } ] }, { \"acquireActions\": [ { \"action\": \"Gs2Inventory:AcquireItemSetByUserId\", \"request\": \"...\" } ] } ], \"missedReceiveRelief\": \"disabled\" } ] } Master data can be registered from the Management Console, or you can set up a workflow that reflects data from GitHub or registers via CI using GS2-Deploy. Transaction Actions GS2-LoginReward provides the following transaction actions: Consume Actions Action Use Gs2LoginReward:MarkReceivedByUserId Marks the specified step as received. Acquire Actions Action Use Gs2LoginReward:DeleteReceiveStatusByUserId Resets the receiving status. Use this when you want the player to receive the login bonus from the beginning again. Gs2LoginReward:UnmarkReceivedByUserId Reverts a specified step to the not-received state. By using “Reset receiving status” as an acquire action, it is possible to perform processes such as restarting the login bonus progress from the beginning when a specific item is acquired or at an event milestone. This allows for periodic campaign resets or providing players with opportunities to re-earn bonuses upon achieving special conditions. Example implementation Receiving login bonuses ReceiveAsync automatically receives the next bonus available for receipt. Distributed items are returned as an EzTransactionDomain , so call WaitAsync on the return value to apply the result. Receiving rewards for missed days (missed-receive relief) By calling MissedReceiveAsync , you pay the cost defined in missedReceiveReliefConsumeActions to receive a specific past step that was missed. Get the receipt status of the login bonus ReceiveStatus.ReceivedSteps contains an array of booleans indicating whether each step has been received. This can be used, for example, when displaying a calendar UI that shows “Day N received”. Check the contents of the login bonus When displaying a preview in the UI of “the reward to be obtained tomorrow” or “the reward to be obtained on the last day”, you can obtain the AcquireActions of each step from the Rewards of the BonusModel . Detailed Reference Reference of GS2-LoginReward","lang":"en","section":"microservices","summary":"Login bonus feature","title":"GS2-LoginReward","url":"/microservices/login_reward/"},{"content":"This is a mechanism for implementing gachas. GS2-Lottery supports both normal gachas and box gachas. graph TD Trigger[\"Lottery trigger (GS2-Showcase purchase reward / quest clear reward, etc.)\"] --\u003e LotteryModel[\"LotteryModel (lottery model)\"] LotteryModel -- \"mode = normal\" --\u003e Normal[\"Normal mode lottery\"] LotteryModel -- \"mode = box\" --\u003e Box[\"Box mode lottery\"] Normal --\u003e PrizeTable[\"Prize table (PrizeTable)\"] Box --\u003e BoxData[\"Player-exclusive box\"] PrizeTable --\u003e Prize[\"Prize (acquireActions)\"] BoxData --\u003e Prize Prize --\u003e Acquire[\"GS2-Distributor reward distribution\"] Normal Gacha A normal gacha performs a pure lottery with the specified probability. Prize Table A prize table defines the emission probability of prizes that appear when the gacha is executed. It is defined as master data. Weights The probability in a prize table is set by specifying a weight for each prize. Specifically, you will create a table such as the following. Weight Prize A 1 Prize B 2 Prize C 4 Interpreted as percentage probabilities, this can be read as follows. Weight Probability Prize A 1 14.285% Prize B 2 28.571% Prize C 4 57.143% When setting probabilities on a percentage basis, you must ensure they all add up to 100%, but when setting them on a weight basis, there is no such burden. Nesting Prize Tables Prize tables can be nested up to 5 layers deep. A specific use case is when you want to set characters to be emitted based on a basic policy such as: SSR characters at 3% emission probability SR characters at 7% emission probability R characters at 90% emission probability In this case, you would define 4 prize tables in 2 tiers. Prize table for rarity lottery Weight Prize type Lottery table name SSR 3 Nested prize table Prize table for SSR character lottery SR 7 Nested prize table Prize table for SR character lottery R 90 Nested prize table Prize table for R character lottery Prize table for SSR character lottery Weight Prize type Lottery table name SSR-0001 1 Acquire action Record SSR-0001 in GS2-Dictionary SSR-0002 1 Acquire action Record SSR-0002 in GS2-Dictionary SSR-0003 1 Acquire action Record SSR-0003 in GS2-Dictionary Prize table for SR character lottery Weight Prize type Lottery table name SR-0001 1 Acquire action Record SR-0001 in GS2-Dictionary SR-0002 1 Acquire action Record SR-0002 in GS2-Dictionary SR-0003 1 Acquire action Record SR-0003 in GS2-Dictionary Prize table for R character lottery Weight Prize type Lottery table name R-0001 1 Acquire action Record R-0001 in GS2-Dictionary R-0002 1 Acquire action Record R-0002 in GS2-Dictionary R-0003 1 Acquire action Record R-0003 in GS2-Dictionary Box Gacha In a box gacha, prizes defined in the master data are placed into a box in the specified quantities, and the lottery is performed by drawing prizes from the box. In other words, if you prepare a box that contains one “winning” prize out of 100 prizes, the winning prize is guaranteed to be drawn within 100 draws. Placing Prizes into the Box The prize table is also used to configure the contents of the box. In normal lottery mode, you set the emission weight, but in box mode the weight parameter specifies the number of prizes to place into the box. Weight Prize A 1 Prize B 2 Prize C 4 In this case, the box initially contains 7 prizes: 1 Prize A, 2 Prize B, and 4 Prize C. Warning In box mode, when the first lottery is performed, a shuffled array of the contents of the box is prepared, and the lottery process pays out prizes in order from that array. Therefore, changing the contents of the prize table for a box that has been drawn from at least once will cause unintended behavior. Resetting the Box A box can be returned to its initial state using the “Reset box” action. Since each player has their own independent box, this can be used for purposes such as resetting the box after granting a completion reward, or refreshing the box at the start of each month. Lottery Model A lottery model specifies which of the prize tables can be used by the lottery API. It is defined as master data. In the example above, it would be problematic if calling the lottery API could directly use the “Prize table for SSR character lottery” to run a lottery. By defining master data for the lottery model such as: Lottery model name Prize table name gacha Prize table for rarity lottery When invoking the lottery process, you specify “gacha” as the lottery model name. Lottery Mode (mode) and Lottery Method (method) A lottery model uses mode to specify the lottery method and method to specify how the prize table is referenced. mode Description normal Normal mode (performs an independent lottery with the specified probability each time) box Box mode (draws prizes from the player’s own box) method Description prize_table Use a statically specified prize table script Dynamically select a prize table using GS2-Script Selecting Prize Tables via Script By setting method to script and specifying choicePrizeTableScriptId , you can invoke GS2-Script when the lottery is executed to dynamically select the prize table to be used. This enables per-player probability changes (such as pity systems) and switching prize tables according to the event currently in progress. Script Triggers By setting lotteryTriggerScriptId on the namespace, you can execute GS2-Script synchronously before the lottery process. The script can decide whether to allow or deny the lottery, or override the lottery result. The main event triggers and the script setting names that can be configured are as follows. lotteryTriggerScriptId : Executed synchronously before the lottery process You can implement custom processing such as verifying lottery results or replacing results under specific conditions. Transaction Actions GS2-Lottery provides the following transaction actions. Acquire action: Execute a lottery, Reset a box By using “Execute a lottery” as an acquire action, you can directly run a gacha (lottery) as a reward for purchasing an item at a shop or as a quest clear reward. Furthermore, by including “Reset a box” as an acquire action, you can safely control, within a transaction, automatic resetting of a box gacha so it can be drawn from the start again, for example when a specific item is acquired or at a milestone in an event. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. LotteryModel : Lottery model. Defines the lottery method and the prize table to use. PrizeTable : Prize table. Defines the weight of each prize together with acquire actions, or a nested prize table. Prize : The unit of a prize. Specifies the reward obtained via acquireActions , and can also configure emission limits and failover destinations via drawnLimit and limitFailOverPrizeId . In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. The following is an example of master data in JSON. { \"version\": \"2019-02-21\", \"lotteryModels\": [ { \"name\": \"lottery-0001\", \"metadata\": \"Normal gacha\", \"mode\": \"normal\", \"method\": \"prize_table\", \"prizeTableName\": \"rarity\" } ], \"prizeTables\": [ { \"name\": \"rarity\", \"metadata\": \"Rarity lottery\", \"prizes\": [ { \"prizeId\": \"ssr\", \"type\": \"prize_table\", \"prizeTableName\": \"ssr-prizes\", \"weight\": 3 }, { \"prizeId\": \"sr\", \"type\": \"prize_table\", \"prizeTableName\": \"sr-prizes\", \"weight\": 7 }, { \"prizeId\": \"r\", \"type\": \"prize_table\", \"prizeTableName\": \"r-prizes\", \"weight\": 90 } ] } ] } Implementation Examples Executing a Lottery Executing a lottery cannot be performed with game engine SDKs. Please implement it by, for example, executing the lottery as a reward for purchasing an item via GS2-Showcase. By including the DrawByUserId of GS2-Lottery in the acquireActions of GS2-Showcase, you can run the lottery as part of the purchase transaction. Obtaining Emission Probabilities For displaying prizes, you can obtain the current emission probabilities for the player. If emission quantity limits (described later) apply, the returned probabilities reflect that effect. Retrieving the Contents of a Box Resetting a Box Retrieving the List of Lottery Models To display a list of gachas in the UI, you can retrieve the lottery models defined in the namespace. Other Features Limiting the Emission Quantity of Prizes When operating in normal mode, you can set an upper limit on the emission quantity per prize. Using this feature causes a discrepancy between the probabilities returned by the Probabilities function and the actual probabilities. This feature should not be used when you are displaying emission probabilities using Probabilities. The intended use case is for lottery processes that distribute physical prizes. For example, if you have a gift certificate that is emitted with 1% probability but you have only 100 gift certificates prepared, this feature is useful. You set the emission quantity limit for the gift certificate to 100, and set a failover prize such as a blank or a different winning prize. With this setting, when 100 gift certificates have already been emitted and another gift certificate would have been drawn, the prize configured as the failover prize is emitted instead. If a quantity limit is set on the failover prize as well, the same kind of limit applies. Detailed Reference GS2-Lottery Reference","lang":"en","section":"microservices","summary":"Lottery processing feature\n","title":"GS2-Lottery","url":"/microservices/lottery/"},{"content":"A feature that groups players based on conditions. It can be used to find opponents. Script Triggers By configuring createGatheringTriggerScriptId , completeMatchmakingTriggerScriptId , and changeRatingScript on the namespace, you can execute custom scripts when a gathering is created, when matchmaking completes, and when ratings change. The main configurable event triggers and the script setting names are as follows. createGatheringTriggerScriptId : When a gathering is created completeMatchmakingTriggerScriptId : When matchmaking completes changeRatingScript : When a rating changes Push Notifications The main push notifications you can configure and their setting names are as follows. joinNotification : Notifies when joining a match leaveNotification : Notifies when leaving a match completeNotification : Notifies when a match is completed changeRatingNotification : Notifies when a rating changes All notifications can be delivered via GS2-Gateway and can also be forwarded as mobile push notifications to offline devices. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. RatingModel : Rating calculation settings SeasonModel : Season period settings In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. Additional Settings Enabling enableDisconnectDetection detects disconnections during matchmaking, and disconnectDetectionTimeoutSeconds adjusts the timeout. By configuring enableCollaborateSeasonRating , when matchmaking completes, GS2-Matchmaking integrates with GS2-SeasonRating and generates a session that accepts results. Transaction Actions GS2-Matchmaking provides the following transaction actions. Verify action: Verify participation in a persistent gathering By using “Verify participation in a persistent gathering” as a verify action, you can set up rewards that can only be received by players who belong to a specific season gathering (team or cluster). This allows safe control within a transaction of measures such as seasonal group competition events or incentives restricted to specific communities. Use-Case Design Guide Matchmaking with Party Tokens If you want to refill the slot after one player leaves a completed match, or if you want to form a party in advance and then run matchmaking, use “party tokens”. Each party member issues a player token (valid for 3 minutes) and sends it to the party leader. The leader sends them to the party-token issuing API to obtain a party token (valid for 10 minutes), and then invokes gathering creation or gathering search. This way, a gathering can be created or joined with all party members already present. Matchmaking Between Parties For example, in a 4 vs 4 battle where you do not want pre-formed parties to be split, you can first run a 4-player matchmaking to create per-party gatherings, and then have each party leader perform a 2-player matchmaking. This realizes party-vs-party matchmaking. Communication Between Players During Matchmaking If players need to interact before matchmaking completes, you can use one of the following two methods when creating the gathering. Creating a chat room with GS2-Chat : Suitable for low-frequency metadata exchange (up to 3 times per second) Launching a game server with GS2-Realtime : Suitable for high-frequency communication, or for letting players play before the required number of participants has been reached Processing After Matchmaking Completes When matchmaking completes, players can be notified using the following methods. In-game push notifications using GS2-Gateway Job registration via GS2-JobQueue You can also execute arbitrary scripts using GS2-Script. When using GS2-Realtime, you can create a GS2-Realtime gathering within the GS2-Script executed after matchmaking completes, and notify the IP address and port information via push notifications or the job queue, guiding players to the game server. Excluding Players via Blacklists You can specify a blacklist of user IDs when creating or searching for a gathering. The blacklist specified at search time is added to the blacklist of the gathering joined. If you are on a blacklist, you are excluded from matchmaking. Standard Matchmaking Gathering A gathering is a group of players grouped together by the matchmaker. The lifecycle of a gathering starts when a player explicitly creates it. Other players run matchmaking and, if the conditions match, they join the gathering. When the number of players specified when the gathering was created is reached, the matchmaking result is notified to the players and the gathering is deleted from GS2-Matchmaking. Attributes A player can have up to 5 attribute values. When creating a gathering, you specify the range of each attribute value for the players you want to recruit. For example, suppose you have a player with the following attribute values. Attribute Name Attribute Value GameMode 1 Stage 10 Level 5 Let GameMode represent the game mode the player wants: whether to match against players worldwide (1) or per region (2=JP, 3=US, 4=EU). Let Stage represent the type of in-game stage the player wants to use for the match. Finally, Level is the player’s skill level. Let’s consider what conditions the gathering should be created with when this player creates a gathering to find opponents. Attribute Name Attribute Value (Min) Attribute Value (Max) GameMode 1 1 Stage 10 10 Level 2 8 The range settings above would be appropriate. GameMode and Stage must match exactly, otherwise players cannot play under the conditions they want. For Level, target players within 3 above or below the player’s level. By creating a gathering with these settings, players who meet the conditions will join the gathering when they submit a matchmaking request. Roles When creating a gathering, you need to set the number of players to recruit. When setting this, you can set the number of players to recruit per role. If there are no specific roles in the game, configure a single role named “default” and specify the number of players you want to gather as the capacity of that role. You need to specify roles in games that have role-based gameplay. For example, in an MMORPG, players have in-game roles such as tank, healer, and DPS depending on their class. If matchmaking ends up with 4 healers, the content cannot be cleared. Each role must be matched in a balanced way. In such cases, configure roles and recruitment numbers as follows. Role Name Capacity Tank 1 Healer 1 DPS 2 Then, when a player submits a matchmaking request, they specify not only attribute values but also their own role. This way, slot management is performed per role and matchmaking is executed. Role Aliases Here is an example of role-based matchmaking with more complex condition settings. Suppose DPS has two sub-types: melee DPS and ranged DPS. The basic matchmaking conditions can be as explained above, but the gathering creator might prefer to have exactly one melee DPS and one ranged DPS. In that case, the condition settings would be as follows. Role Name Capacity Tank 1 Healer 1 Melee DPS 1 Ranged DPS 1 Players then specify “melee DPS” or “ranged DPS” rather than “DPS” when matchmaking. However, with this setup, a player who says “I’m fine being either melee or ranged as long as 2 DPS are gathered” can no longer match. That is where the role alias feature is useful. The part where players set their role as “melee DPS” or “ranged DPS” does not change, but the condition settings used when creating the gathering change. Role Name Aliases Capacity Tank [] 1 Healer [] 1 DPS [Melee DPS, Ranged DPS] 2 This way, players whose role is “melee DPS” or “ranged DPS” can also fill DPS slots. Rating Calculation A feature is provided to calculate a rating value that represents the player’s strength. The initial rating value is 1500 and goes up or down depending on the result of the game. When players with a large rating gap play against each other and the higher-rated player loses, the higher-rated losing player’s rating drops significantly, while the lower-rated winning player’s rating rises significantly. This characteristic produces ratings that reflect player skill. Voting To change a rating value, a voting process is required. When the match is over and the ranking is finalized, each player sends the game result to the server. The server accepts votes per gathering and closes voting when all players have voted, or 5 minutes after the first player voted. The server takes a majority vote and finalizes the result. This process means that even if there are malicious players who vote dishonestly, their votes do not influence the final result. A new rating value is calculated and reflected based on the ranking finalized by the majority vote. Tied Voting Results If the majority vote is tied and the final result cannot be determined, the rating calculation is not performed. Therefore, it is difficult to obtain correct rating values in a 1v1 game. To solve this, you can devise a workaround such as matchmaking a third player who is not directly involved in the match and having that player vote from a third-party perspective. Expiration of a Gathering In principle, once a gathering is created, it will not be deleted until matchmaking succeeds or all players have left. Especially in games with few players, if a player ends the game during matchmaking without calling the cancel API, it is possible that another player submits a matchmaking request, matchmaking succeeds, and yet the player who created the gathering no longer exists. To easily solve this problem, you can set an expiration for the gathering at creation time. By specifying a specific time, or an elapsed time from creation, the gathering will be deleted at that time. At that point, any players who have already joined the gathering will be automatically removed. Implementation Examples Creating a Gathering Running Matchmaking Leaving a Gathering Getting the Rating Value Retrieving a Ballot Submitting a Vote Frequently Asked Questions I want to list existing gatherings and let players choose one GS2-Matchmaking does not provide such a feature. This is not for technical reasons; it is a policy decision by us as fellow game developers, intended to avoid harming the player experience. If players choose from a list of existing gatherings, you can present them with the best way to join. However, between retrieving the list and actually performing the join operation, a delay is introduced by the user’s input. Because of this delay, it is unavoidable that, by the time players select the gathering they want to join, the gathering is already full. GS2 developers have played many games like this in the past and felt enormous frustration with them. We are confident that GS2-Matchmaking provides a mechanism that can automatically find the most appropriate gathering for the player without requiring them to select one themselves. For that reason, we do not provide such a feature. I want to set a password on a gathering Set the password as one of the attribute values and use it as part of the matchmaking conditions. Season Matchmaking Season matchmaking creates a gathering that persists for a specified period. Rather than matchmaking for real-time matches, the common use case is to form clusters that persist for a specific period, and combine them with GS2-Ranking2 cluster rankings to realize rankings within a gathering. Season When using season matchmaking, you set the period by specifying an event in GS2-Schedule. If the event has a repeat setting, a new gathering is formed each time it repeats. Tier By combining season matchmaking with GS2-Experience, players within a specific rank can be matched together. The GS2-Ranking2 cluster ranking has a feature for setting ranking rewards, allowing top-ranked players to be granted experience so they can move up to a higher tier. Maximum Number of Players In season matchmaking, up to 1000 players can be matched. Matchmaking Conditions Season matchmaking does not allow complex search conditions like standard matchmaking. There is only one parameter available for search conditions: the rank from GS2-Experience. The value is not passed as an API argument; GS2-Matchmaking obtains the value internally from GS2-Experience. If the integration with GS2-Experience is not used, matchmaking targets all players. Leaving a Persistent Gathering With standard matchmaking, you could leave a matched gathering. However, with season matchmaking you cannot leave; if you have already matched and submit another matchmaking request, the gathering you have already joined is returned. In other words, during the season there is in principle no way to re-match into a different gathering. There is one exception: when the persistent gathering is deleted. By deleting the persistent gathering, the players in it will be matched into a new gathering the next time they perform matchmaking. Matchmaking Process Priority In season matchmaking, when matchmaking, the system searches for a persistent gathering of the same tier that has not yet reached its capacity and joins it. If no joinable gathering exists, the API automatically creates a gathering, performs the join process, and then responds. If multiple joinable gatherings exist, the gathering with more participants is given priority. Behavior When Matchmaking Conflicts A matchmaking join operation generally completes within a few milliseconds, but even so, the same gathering can be selected as a join candidate simultaneously. To prevent more players than the configured capacity from joining, GS2-Matchmaking takes a lock on the gathering before processing the player’s join. As a result, even if a joinable gathering exists, it is excluded from matchmaking candidates for a brief moment while another player’s join is being processed, and another candidate is selected instead. Because of this behavior, if you prepare a persistent gathering with a maximum capacity of 1000 and 1000 players of the same tier submit matchmaking requests at exactly the same time, you will not necessarily end up with a single persistent gathering of 1000 participants; the players may be split across multiple persistent gatherings. At this time, players are joined into the gathering with the most participants whenever possible, so the following kinds of results are generally expected. Participants in Gathering A Participants in Gathering B Participants in Gathering C 1000 - - 999 1 - 998 1 1 997 2 1 995 4 1 995 5 - 990 8 2 This result is just one example; different patterns can occur. Detailed Reference GS2-Matchmaking Reference","lang":"en","section":"microservices","summary":"Matchmaking feature\n","title":"GS2-Matchmaking","url":"/microservices/matchmaking/"},{"content":"GS2-MegaField provides the ability to efficiently share and synchronize the position information of a large number of players in a huge 3D space. In titles such as MMORPGs, open worlds, and metaverse-style services where a large number of players log in to the same world simultaneously, distributing every player’s position to every player would overwhelm both network bandwidth and CPU. GS2-MegaField solves this problem by efficiently retrieving “only the players near you”. Areas and Layers The space of GS2-MegaField is composed of two concepts: “Area” and “Layer”. AreaModel: Master data that represents a single large 3D space. For example, you create one per logical section within a world such as “the inside of a town”, “a dungeon”, or “a field”. LayerModel: Per-purpose layers that exist within a single area. For example, you can stack the same location for different purposes such as “for players”, “for NPCs”, or “for items”. An area model contains multiple layer models and is defined as master data. A player’s position is expressed as “in which area, on which layer, and at which coordinates”. graph TD AreaModel[\"AreaModel: town\"] --\u003e LayerPlayer[\"LayerModel: player\"] AreaModel --\u003e LayerNpc[\"LayerModel: npc\"] AreaModel --\u003e LayerItem[\"LayerModel: item\"] Player1[\"Player A\"] -- Spot --\u003e LayerPlayer Player2[\"Player B\"] -- Spot --\u003e LayerPlayer Spatial Index GS2-MegaField manages player positions within a layer using a spatial index (a structure based on R-Tree). This allows neighborhood searches such as “get all players within N meters around me” to be processed efficiently regardless of the number of players. The spatial index is independent per layer, so you can handle different searches such as “proximity between players” and “proximity to NPCs” separately. Player position information Each player sends their “current position” to GS2-MegaField as MyPosition . MyPosition includes the following information. position: 3D coordinates (x, y, z) vector: Direction vector (x, y, z) r: Radius of vision / interest When sending a position, the player can simultaneously specify the “range they are interested in” as a Scope , and receive information about other players within that range as a response. Scope includes the following information. layerName: Name of the layer to be searched r: Search radius limit: Maximum number of results to return By specifying multiple Scope s, you can also retrieve neighboring players from multiple layers simultaneously. Position synchronization between game clients GS2-MegaField provides player position information as “a thinned-out list of nearby players”. This list contains each player’s position, direction vector, and last sync time, and the game client can render with smooth position synchronization by interpolating this information. However, GS2-MegaField itself is not a always-on protocol that guarantees real-time performance. For cases that require high-frequency action synchronization or strict input-based synchronization, combining with GS2-Realtime is effective. Transaction Actions GS2-MegaField does not provide transaction actions. Master Data Management Registering master data allows you to configure data and behaviors available to the microservice. Master data types include: AreaModel : Definition of a logical section (area) within the world LayerModel : Definition of per-purpose layers within an area (defined as a child of AreaModel) Below is a JSON example of master data that configures AreaModel / LayerModel: { \"version\": \"2019-09-09\", \"areaModels\": [ { \"name\": \"town\", \"metadata\": \"starter town\", \"layerModels\": [ { \"name\": \"player\", \"metadata\": \"players\" }, { \"name\": \"npc\", \"metadata\": \"npcs\" } ] }, { \"name\": \"dungeon\", \"layerModels\": [ { \"name\": \"player\" }, { \"name\": \"enemy\" } ] } ] } Master data can be registered via the management console, imported from GitHub, or registered from CI using GS2-Deploy. Example Implementation Get list of area models Retrieve which areas exist in the world. Update your position and get nearby players Register your current position with GS2-MegaField and retrieve the list of other players around you. Typical usage is to repeatedly call this at regular intervals to update the position. Reference the position information of a specific player You can also directly retrieve the position information of a player whose user ID is known. More practical information Combining with GS2-Realtime GS2-MegaField is suited for handling the “macro-scale arrangement of players in a vast world”. On the other hand, it is not suitable for scenes that require millisecond-level synchronization, such as close-range combat or cooperative play with friends. In such cases, a hybrid configuration is effective: use the nearby players obtained from GS2-MegaField as a trigger to aggregate them into a GS2-Realtime room, and perform real-time communication only between nearby players. graph LR Player[\"Player\"] -- Macro position sync --\u003e MegaField[\"GS2-MegaField\"] MegaField -- Nearby players --\u003e Player Player -- Close-range combat, etc. --\u003e Realtime[\"GS2-Realtime\"] Realtime -- Same-room players --\u003e Player Designing update frequency The call frequency of position updates directly translates into server load and network bandwidth. In general, a design that updates at a frequency lower than the rendering frame rate (for example around 5 to 10 Hz) and performs interpolation on the client side tends to be the most balanced. Optimizing Scope specification The radius and result count limit specified in Scope should be adjusted according to the game’s view range and presentation. If all players perform searches with a large radius and many results, the load becomes high; it is effective to query with a smaller radius and fewer results for off-screen determinations, and obtain a wider range only when focused. Detailed Reference Reference of GS2-MegaField","lang":"en","section":"microservices","summary":"Efficient player position synchronization in large 3D spaces\n","title":"GS2-MegaField","url":"/microservices/mega_field/"},{"content":"A mechanism for rewarding players based on actions they have accumulated in the game. It is used to implement features generally referred to as achievements, trophies, and missions. graph TD Action[\"In-game action (quest clear / gacha draw, etc.)\"] -- \"Increase counter (IncreaseCounterByUserId)\" --\u003e Counter[\"Mission counter (Counter / Scope)\"] Counter -- \"Target value reached\" --\u003e Task[\"Mission task (MissionTaskModel)\"] Task -- \"ReceiveRewards\" --\u003e Reward[\"completeAcquireActions\"] Reward --\u003e Distributor[\"GS2-Distributor reward distribution\"] Task --\u003e Group[\"Mission group (MissionGroupModel)\"] Group -- \"Reset receipt flag based on resetType\" --\u003e Task Mission Counter An entity for counting the number of times based on a player’s actions. Counters are provided to count in-game action counts such as the number of times a quest has been cleared, the number of times a character has been enhanced, or the number of times a gacha has been drawn. A counter can have scopes. The following values can be set for a scope. Scope Type Scope Content Not reset Cumulative total since gameplay started Reset at X o’clock daily Number of times executed today Reset at X o’clock on day-of-week X weekly Number of times executed this week Reset at X o’clock on day X of every month Number of times executed this month Reset every fixed number of days Reset every specified number of days from a base time Count up only when a verify action matches Increment counter based on the result of a verifyAction Counter values are managed per scope, and the value of each scope can be used as a mission achievement condition. graph LR Up[\"Increase counter request\"] --\u003e Counter[\"Counter\"] Counter --\u003e Scope1[\"Scope 1 Not reset\"] Counter --\u003e Scope2[\"Scope 2 Reset daily\"] Counter --\u003e Scope3[\"Scope 3 Reset weekly\"] Scope1 -- ScopedValue --\u003e Mission1[\"Cumulative 100 times mission\"] Scope2 -- ScopedValue --\u003e Mission2[\"Daily 10 times mission\"] Scope3 -- ScopedValue --\u003e Mission3[\"Weekly 50 times mission\"] Scope Control with Verify Actions By using scopeType=verifyAction , you can define arbitrary conditions with conditionName and condition , and control whether to increment the counter based on the verification result of another microservice. This makes it possible to create scopes that only increment during a specific event period, or that only increment when a specific character is in the formation. Challenge Period CounterModel can be configured with challengePeriodEventId , where specifying a GS2-Schedule event GRN limits the period during which the counter can be operated. Counters cannot be updated outside the specified period, which is useful for limited-time events. Mission Task This is master data that defines the goals presented to the player. It defines a “mission counter”, a “scope”, a “target value”, and a “reward” obtained when the target is met. For example, the following settings can be configured. Mission Counter Scope Type Target Value Reward Number of quest clears Reset at X o’clock daily 10 Item A Number of quest clears Reset at X o’clock on day-of-week X weekly 50 Item B Number of character enhancements Reset at X o’clock daily 5 Item C Task Dependencies By specifying premiseMissionTaskName , you can define missions that can only be received after completing a preceding task. You can build a stepwise achievement flow such as “completing task A makes task B receivable”. Achievement Decisions Using Verify Actions By specifying verifyActions for verifyCompleteType , achievement of a task can be decided by whether verify actions from other microservices are satisfied. When this feature is used, the achievement decision via the Complete object provided by GS2-Mission (server-side automatic decision) is not performed. Therefore, the achievement state must be computed on the client to control the receipt UI, and the reward receipt action must be explicitly executed. To re-evaluate achievability on the server side, you can call the EvaluateComplete API to refresh the Complete state. Challenge Period MissionTaskModel ’s challengePeriodEventId lets you limit the achievable period using a GS2-Schedule event. Achieved tasks can still be received after the period ends, but if a reset interval is configured on the mission task, they become unreceivable when the reset timing arrives. Mission Group An entity that bundles multiple mission tasks. A mission group can have a reset cycle for the reward receipt flag. Mission Counter Scope Type Target Value Reward Number of quest clears Reset at X o’clock daily 10 Item A Number of character enhancements Reset at X o’clock daily 5 Item C By associating these mission tasks with a single mission group and configuring the mission group’s reward receipt flag reset cycle to “Reset at X o’clock daily” as well, players can receive rewards every day as long as they complete the mission tasks daily. Reset Type resetType can be one of the following. resetType Description notReset Do not reset (for achievement/trophy-like usage) daily Reset daily at resetHour weekly Reset weekly on resetDayOfWeek at resetHour monthly Reset monthly on resetDayOfMonth at resetHour days Reset every days days starting from anchorTimestamp Resetting Every Arbitrary Number of Days By specifying days for resetType , you can reset the reward receipt flag every specified number of days from the base time specified in anchorTimestamp . For example, you can run an operation that resets every 3 days from the start of an event. Script Triggers By configuring missionCompleteScript , counterIncrementScript , and receiveRewardsScript on the namespace, you can invoke custom scripts at the timing of mission completion, counter increment, and reward receipt. The main event triggers and the script setting names that can be configured are as follows. missionCompleteScript : Mission completion counterIncrementScript : Counter increment receiveRewardsScript : Reward receipt By leveraging these, you can customize BI integration on completion, detection of illegitimate counter operations, and special processing on reward receipt. Push Notifications The main push notifications and their setting names are as follows. completeNotification : Notifies when a mission task is completed Mobile push forwarding to offline devices is also supported, encouraging players to receive their rewards. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. CounterModel : A list of CounterScopeModel defining counting targets and reset cycles MissionGroupModel : Group-level reset settings and the tasks belonging to it MissionTaskModel : Achievement conditions (counter and target value) and the reward for achievement In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. The following is an example of master data in JSON. { \"version\": \"2019-04-12\", \"counters\": [ { \"name\": \"quest_complete\", \"metadata\": \"Quest clear count\", \"scopes\": [ { \"scopeType\": \"resetTimingScope\", \"resetType\": \"daily\", \"resetHour\": 5 }, { \"scopeType\": \"resetTimingScope\", \"resetType\": \"weekly\", \"resetDayOfWeek\": \"monday\", \"resetHour\": 5 } ] } ], \"missionGroups\": [ { \"name\": \"daily-mission\", \"metadata\": \"Daily mission\", \"resetType\": \"daily\", \"resetHour\": 5, \"tasks\": [ { \"name\": \"mission-task-0001\", \"metadata\": \"Clear 10 quests\", \"counterName\": \"quest_complete\", \"targetResetType\": \"daily\", \"targetValue\": 10, \"completeAcquireActions\": [] } ] } ] } GS2-Buff Integration By integrating with GS2-Buff, you can apply buffs to the completeAcquireActions of mission task models to flexibly adjust reward amounts according to events and other factors. Transaction Actions GS2-Mission provides the following transaction actions. Verify action: Verify mission achievement status, verify counter value Consume action: Receive rewards (including batch), decrement or reset a counter Acquire action: Increment or set a counter, restore reward receipt state (mark as unreceived) By using “Increment counter” as an acquire action, you can directly advance mission progress as a reward for purchasing an item at a shop or clearing a quest. Also, by using “Decrement counter” as a consume action, you can safely operate within a transaction to consume a mission counter as a cost for a specific benefit (for example, a point-consumption mission). Implementation Examples Incrementing a Mission Counter Incrementing a mission counter cannot be performed with game engine SDKs. Please implement it by, for example, incrementing a counter as a GS2-Quest clear reward or a GS2-Lottery prize. If you want to increment a counter directly from the client, the server should issue a transaction and run it as an acquire action via GS2-Distributor. Retrieving Mission Task Achievement Status and Reward Receipt Status Receiving Mission Completion Rewards Batch Receipt of Completed Rewards When you want to receive all completed but unclaimed tasks at once, you can use BatchReceiveRewards . By specifying multiple missionTaskName values, the rewards are received as a single transaction. Re-evaluating Task Achievement Using Verify Actions Call this when you want to re-evaluate on the server the achievement status of tasks for which verifyCompleteType is set to verifyActions . Retrieving the Mission Counter Value Resetting a Mission Counter You can manually reset the counter value for a specific scope. This can be used to initialize event-related counters at the end of an event. Retrieving the Mission Target Values Detailed Reference GS2-Mission Reference","lang":"en","section":"microservices","summary":"Mission and achievement feature\n","title":"GS2-Mission","url":"/microservices/mission/"},{"content":"Warning GS2-Money2 has been released. Unless there is a special reason, please use GS2-Money2 for new use cases. A feature that handles in-game resources whose value is equivalent to cash. Be sure to use this feature when handling assets that fall under prepaid payment instruments (self-issued type) as defined by the Japanese Payment Services Act. Balance GS2-Money does not manage a player’s billing currency balance as a simple quantity; instead, it manages quantities per the value at the time of purchase. For example, if 100 units of billing currency are purchased for 100 yen, the value of one unit is equivalent to 1 yen. Now suppose 1,200 units of billing currency can be purchased simultaneously for 1,000 yen. One option is to keep the unit price at 1 yen and treat the extra 200 units as a free bonus; another option is to treat the units purchased for 1,000 yen as having a different unit price of 0.8334 yen. If the latter approach is adopted, GS2-Money has the ability to separately manage the “balance of billing currency with a unit price of 1 yen” and the “balance of billing currency with a unit price of 0.8334 yen”. graph TD Wallet[\"Wallet (distinguished by slot number)\"] Wallet --\u003e Paid[\"Paid currency (paid)\"] Wallet --\u003e Free[\"Free currency (free)\"] Paid --\u003e Detail1[\"Balance with unit price 1 yen\"] Paid --\u003e Detail2[\"Balance with unit price 0.8334 yen\"] Paid --\u003e Detail3[\"...per purchase value\"] What is the benefit of choosing the latter? Obviously, the latter makes accounting more complex and may seem to offer no benefit. From the service provider’s perspective, that is entirely true. However, let us switch sides and think from the game player’s perspective. Some games have a billing currency with a cash value of 0 yen (commonly called “free currency”) that is distributed by the operator. To encourage players to purchase billing currency, suppose an attractive product is sold for 300 units that can only be purchased with billing currency obtained by paying real money (commonly called “paid currency”). If a player purchases 1,200 units of billing currency for 1,000 yen and the system grants 1,000 paid-currency units and 200 free-currency units, the player can only purchase the 300-unit product three times. On the other hand, if you treat all 1,200 units as paid currency with a unit price of 0.8334 yen, the player can purchase it four times. This difference has at least some impact on player psychology. Whether to prioritize accounting convenience or player benefit is a specification that should be considered carefully. Slots GS2-Money supports multiple wallets per player. The key used to distinguish these wallets is the slot. This feature exists in order to comply with the guidelines of platform providers that prohibit bringing in billing currency purchased on other platforms. However, since these guidelines only apply to paid currency, there is a feature that allows free currency to be shared across all slots. By setting the namespace’s shareFree to true , free currency is treated as a balance shared across all slots. Consumption Priority When a player consumes billing currency, you can choose whether to consume free currency first or paid currency first. Generally, the specification of consuming free currency first is adopted, but for accounting reasons paid currency can be prioritized. When consuming paid currency, the currency with the higher unit price is consumed first. Specify one of the following for the namespace’s priority . priority Description free Consume free currency first paid Consume paid currency first (starting from the highest unit price) We understand that there are needs to consume currencies in the order they were obtained, regardless of whether they are free or paid, or among paid currencies. However, this feature is not currently implemented. If your project requires this, please contact the development team. Receipt Validation GS2-Money has a feature to validate receipts obtained when purchasing additional content from game distribution platforms. The receipt is validated to confirm that it was correctly issued by the platform provider and that it has not been used in the game before. By using this feature, you can prevent attacks that attempt to obtain billing currency using fraudulent receipts. To enable receipt validation, register the following authentication information on the namespace. appleKey : The bundle ID of Apple App Store googleKey : The public key of Google Play enableFakeReceipt : Whether to allow dummy receipts during development Transaction Log Not only the receipt validation history but also all addition and subtraction of billing currency is recorded. Furthermore, several times a day, the system aggregates how much unused billing currency is currently pooled in the game in cash-equivalent terms. The aggregated result is reflected in the balance field of the namespace. Depending on the situation, you may be required to deposit a portion of the unused balance with a third-party institution; this calculated result can be used in such cases. Legal Procedures GS2-Money collects the data required for various legal procedures and makes it accessible through the API, but the legal procedures themselves must be performed by you or your organization as the user of GS2. GS2 cannot take responsibility for what procedures are required, and therefore cannot give advice on it. Please consult your legal counsel. Script Triggers By registering various script settings on the namespace, you can execute custom scripts at the timing of deposit/withdrawal processing or wallet creation. The main event triggers and the script setting names that can be configured are as follows. createWalletScript : When a wallet is created depositScript : When a deposit is processed withdrawScript : When a withdrawal is processed Transaction Actions GS2-Money provides the following transaction actions. Consume action: Consume balance, Record receipt Acquire action: Add to balance, Delete receipt record By using “Add to balance” as an acquire action, you can safely run processes within a transaction that directly grant billing currency (paid or free) upon clearing a specific event or as a gacha “bonus”. This enables flexible measures combining purchases with in-game rewards. Implementation Examples Retrieving the Balance Specifying the wallet slot, retrieve the current paid currency balance ( paid ), free currency balance ( free ), and the breakdown by purchase unit price ( detail ). Adding to the Balance Adding to the balance cannot be performed with game engine SDKs. Implement it by, for example, adding to the balance as a GS2-Showcase purchase reward, or by calling the GS2-Money receipt validation API via server-to-server communication. Consuming the Balance We do not recommend directly consuming the balance via this API. By consuming billing currency through services such as GS2-Showcase, you can safely handle granting items in exchange for consumption as a single transaction. By specifying paidOnly as true , only paid currency will be consumed. Use this when you need to comply with platform provider guidelines. Detailed Reference GS2-Money Reference","lang":"en","section":"microservices","summary":"Billing currency management feature\n","title":"GS2-Money","url":"/microservices/money/"},{"content":"Tip GS2-Money2 is, as its name suggests, a microservice that corresponds to version 2. For documentation on the previous version, see GS2-Money . A feature for handling in-game resources that have a value equivalent to cash. Be sure to use this feature when handling assets that fall under prepaid payment instruments (self-issued type) as defined by the Japanese Payment Services Act. GS2-Money2 is not merely a service that handles “billing currency balances”; it is a microservice that takes on the following accounting and legal-compliance requirements as a whole. Balance management per deposit timestamp and unit price Prevention of fraudulent deposits via receipt validation Retention of wallet deposit/withdrawal history Isolation of currencies in accordance with platform guidelines State management of subscription (period-based) contracts Aggregation of unused balances (compliance with prepaid payment instruments) Balance GS2-Money2 does not manage a player’s billing currency balance as a simple quantity; instead, it manages quantities per the value at the time of purchase. For example, if 100 units of billing currency are purchased for 100 yen, the value of one unit is equivalent to 1 yen. Now suppose 1,200 units of billing currency can be purchased simultaneously for 1,000 yen. One option is to keep the unit price at 1 yen and treat the extra 200 units as a free bonus; another option is to treat the units purchased for 1,000 yen as having a different unit price of 0.8334 yen. If the latter approach is adopted, GS2-Money2 has the ability to separately manage the “balance of billing currency with a unit price of 1 yen” and the “balance of billing currency with a unit price of 0.8334 yen”. What is the benefit of choosing the latter? Obviously, the latter makes accounting more complex and may seem to offer no benefit. From the service provider’s perspective, that is entirely true. However, let us switch sides and think from the game player’s perspective. Some games have a billing currency with a cash value of 0 yen (commonly called “free currency”) that is distributed by the operator. To encourage players to purchase billing currency, suppose an attractive product is sold for 300 units that can only be purchased with billing currency obtained by paying real money (commonly called “paid currency”). If a player purchases 1,200 units of billing currency for 1,000 yen and the system grants 1,000 paid-currency units and 200 free-currency units, the player can only purchase the 300-unit product three times. On the other hand, if you treat all 1,200 units as paid currency with a unit price of 0.8334 yen, the player can purchase it four times. This difference has at least some impact on player psychology. Whether to prioritize accounting convenience or player benefit is a specification that should be considered carefully. Slots GS2-Money2 supports multiple wallets per player. The key used to distinguish these wallets is the slot. This feature exists in order to comply with the guidelines of platform providers that prohibit bringing in billing currency purchased on other platforms. However, since these guidelines only apply to paid currency, there is a feature that allows free currency to be shared across all slots. By enabling the namespace’s sharedFreeCurrency , free currency is treated as shared across all slots, and only paid currency is isolated per slot. graph LR subgraph Wallets[Wallets] direction TB S0[\"Slot 0 (iOS) Paid balance: 1,000\"] S1[\"Slot 1 (Android) Paid balance: 500\"] S2[\"Slot 2 (Steam) Paid balance: 800\"] end Shared[\"Free balance: 200 (sharedFreeCurrency=true)\"] -.shared.-\u003e S0 Shared -.shared.-\u003e S1 Shared -.shared.-\u003e S2 Purchase Currency A change in GS2-Money2 compared to GS2-Money is that a single wallet can hold billing currency purchased in multiple currencies. For example, paid currency purchased in JPY and paid currency purchased in USD can be held as separate balances within a single wallet. In the daily aggregation process performed several times a day, DailyTransactionHistory is recorded per currency, allowing sales and consumption to be tracked separately per currency. Consumption Priority When a player consumes billing currency, you can choose whether to consume free currency first or paid currency first. Generally, the specification of consuming free currency first is adopted, but for accounting reasons paid currency can be prioritized. When consuming paid currency, the oldest deposits are consumed first. Specify one of the following for the namespace’s currencyUsagePriority . Value Description PrioritizeFree Consume free currency first (typical) PrioritizePaid Consume paid currency first Receipt Validation GS2-Money2 has a feature to validate receipts obtained when purchasing additional content from game distribution platforms. The receipt is validated to confirm that it was correctly issued by the platform provider and that it has not been used in the game before. To validate receipts, you must register Apple App Store or Google Play authentication credentials in the namespace’s platformSetting . By using this feature, you can prevent attacks that attempt to obtain billing currency using fraudulent receipts. Supported Platforms Platform Setting Key Description Apple App Store appleAppStore Billing for iOS / iPadOS / macOS Google Play googlePlay Billing for Android Fake fake Dummy receipt issuance for development and QA During development, you can use fake to issue pseudo receipts and run test flows without executing actual purchases. Transaction Log Not only the receipt validation history but also all addition and subtraction of billing currency is recorded. Furthermore, several times a day, the system aggregates how much unused billing currency is currently pooled in the game in cash-equivalent terms. Depending on the situation, you may be required to deposit a portion of the unused balance with a third-party institution; this calculated result can be used in such cases. Main Log/History Data Data Description DepositEvent History of deposit operations WithdrawEvent History of consumption operations VerifyReceiptEvent History of receipt validations RefundEvent History of refund notifications from the platform RefundHistory History of refund cancellations DailyTransactionHistory Daily aggregation of deposits/withdrawals per currency UnusedBalance Current unused balance per currency Legal Procedures GS2-Money2 collects the data required for various legal procedures and makes it accessible via the API, but the legal procedures themselves must be performed by you or your organization as the user of GS2. GS2 cannot take responsibility for what procedures are required and therefore cannot give advice on it. Please consult your legal counsel. Transaction Actions GS2-Money2 provides the following transaction actions. Consume action: Consume balance, Verify receipt Acquire action: Add to balance By using “Add to balance” as an acquire action, you can safely run processes within a transaction that directly grant billing currency (paid or free) upon clearing a specific event or as a gacha “bonus”. This enables flexible measures combining purchases with in-game rewards. By using “Verify receipt” as a consume action, you can safely handle, as a single transaction, the entire flow from purchase processing using a receipt to adding billing currency. Subscriptions (Recurring Billing) GS2-Money2 can handle not only per-purchase billing currency but also subscriptions (recurring billing). By registering StoreSubscriptionContentModel master data in advance and linking with GS2-Schedule using scheduleNamespaceId and triggerName , the start, renewal, and end of contract periods can be reflected automatically. graph LR Player[\"Player\"] --\u003e|Purchase| Store[\"App Store / Google Play\"] Store --\u003e|Receipt| Player Player --\u003e|AllocateSubscriptionStatus| Money2[GS2-Money2] Money2 --\u003e|Trigger| Schedule[GS2-Schedule] Schedule -.Expiration management.-\u003e Money2 Money2 --\u003e|Notification| Player Contract Information Management Each purchase is recorded in a SubscribeTransaction, allowing contract details and store information per transaction to be tracked. Per-player contract status is stored in SubscriptionStatus, where you can check the current status (active / inactive) and expiresAt . Use AllocateSubscriptionStatus to bind a contract status to a player using a receipt. You can also use TakeOverSubscriptionStatus to transfer the contract to another player. This can be used for operations such as sharing a contract within a family or transferring a contract from a child account to an adult account. Script Triggers per Lifecycle Scripts can be executed before and after contract operations. You can choose synchronous or asynchronous execution, and external service integration is also supported. Trigger Name Main Use subscribeScript On new subscription (excluding user reassignment) renewScript On subscription renewal unsubscribeScript On cancellation (excluding user reassignment) takeOverScript When changing the user assigned to a contract Contract Status Notifications When the subscription status changes, the push notification configured in changeSubscriptionStatusNotification can be sent. Use this to handle changes such as expiration or cancellation during gameplay and reflect them in the UI. Script Triggers By configuring depositBalanceScript , withdrawBalanceScript , and verifyReceiptScript on the namespace, you can execute custom scripts before and after deposit, withdrawal, and receipt validation. Triggers can be set to synchronous or asynchronous execution and support external integration using Amazon EventBridge. The main event triggers and the script setting names that can be configured are as follows. depositBalanceScript (completion notification: depositBalanceDone ): Before and after deposit processing withdrawBalanceScript (completion notification: withdrawBalanceDone ): Before and after withdrawal processing verifyReceiptScript (completion notification: verifyReceiptDone ): Before and after receipt validation You can use synchronous scripts to reject deposits/withdrawals when certain conditions apply, or use asynchronous scripts to send revenue data to BI tools in real time. Push Notifications The main push notifications and their setting names are as follows. changeSubscriptionStatusNotification : Notifies when a subscription’s contract status changes Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. StoreContentModel : Sale content definition StoreSubscriptionContentModel : Subscription content definition In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. Example of StoreContentModel Defines the mapping between sale content and product IDs of the App Store / Google Play. { \"version\": \"2022-07-13\", \"storeContentModels\": [ { \"name\": \"stone_300\", \"metadata\": \"300 stones pack\", \"appleAppStore\": { \"productId\": \"io.gs2.sample.stone_300\" }, \"googlePlay\": { \"productId\": \"io.gs2.sample.stone_300\" } } ] } Buff-Based Adjustment By integrating with GS2-Buff, you can apply buffs to the count of DepositByUserId or the withdrawCount of Withdraw / WithdrawByUserId to temporarily increase or decrease the deposit or consumption amount. You can flexibly adjust these according to events and campaigns. For example, a billing currency bonus campaign such as “increase billing currency purchased during the campaign by 10%” can be implemented as a Rate Add 0.1 buff on the count of DepositByUserId . Implementation Examples Retrieving the Balance Retrieving the List of Wallets You can retrieve all of the player’s wallets per slot at once. This is useful for displaying balances when billing currency is separated across multiple platforms. Adding to the Balance Adding to the balance cannot be performed with game engine SDKs. Implement it by, for example, adding to the balance as a GS2-Showcase purchase reward. Consuming the Balance We do not recommend consuming the balance directly via this API. Instead, we recommend performing some processing in exchange for consuming the billing currency via a service such as GS2-Showcase. Retrieving Subscription Contract Status Allocating a Subscription Contract Using a receipt obtained from the App Store / Google Play, assign a subscription contract to the player. Receipt validation is also performed, and contracts using fraudulent receipts are rejected. Taking Over a Subscription Contract Changes the player a subscription contract is bound to from another player to the current player. The contract on the platform itself is not changed; only the in-game target of the contract is changed. Detailed Reference GS2-Money2 Reference","lang":"en","section":"microservices","summary":"Billing currency management feature","title":"GS2-Money2","url":"/microservices/money2/"},{"content":"A mechanism for delivering in-game announcements in HTML format. The HTML content to be delivered must be generated by hugo ( https://gohugo.io/) . When you upload article data to GS2-News, GS2 builds it with hugo and hosts it as static web content. Game clients can view the announcements by accessing the temporary URLs delivered by GS2. graph LR Author[\"Operator\"] -- \"ZIP upload\" --\u003e GS2[\"GS2-News\"] GS2 -- \"hugo build (pre-generates all public/non-public patterns)\" --\u003e CDN[\"CDN (HTML / ZIP)\"] Player[\"Player\"] -- \"GetContentsUrl\" --\u003e GS2 GS2 -- \"URL + Cookie (valid for 1 hour)\" --\u003e Player Player -- \"WebView or ZIP DL\" --\u003e CDN hugo hugo is a generator for producing static web pages. It generates HTML files by building templates that determine the page layout and design, together with article data written in Markdown format. For details on how to use hugo, refer to the official hugo site or various tutorial sites. GS2 provides a minimal hugo template and sample article data on GitHub. https://github.com/gs2io/gs2-news-sample Articles Linked to Events GS2-News can manage article data that is linked to events managed by GS2-Schedule. You can enable the linkage by writing the following in the front matter of the article data Markdown file. x_gs2_scheduleEventId: ${GS2-Schedule event GRN} In addition, the following placeholders can be used in the GS2-Schedule event ID. Placeholder Substituted Value {region} Region name {ownerId} GS2 owner ID An example is shown below. x_gs2_scheduleEventId: grn:gs2:{region}:{ownerId}:schedule:schedule-0001:event:event-0001 You can automatically control articles that are displayed only while an event is ongoing, or articles that are hidden only during a specific event period, without operating an admin tool. Article Data Size Limit The total article data uploaded to GS2-News must be within 100 MB . Also, the --buildDrafts option is not included when building article data. Content with draft: true in its front matter will not be delivered. Building Article Data Article data delivered by GS2-News is updated by uploading a zip-compressed hugo template and article files. Afterwards, GS2-News builds and delivers the article data. If x_gs2_scheduleEventId is described in the article data, each article is built in advance for both the public and non-public state, and the results are placed on the web server. Then, when a player tries to access the article data, GS2-News responds with the most appropriate content URL based on the current event status. sequenceDiagram participant U as Operator participant N as GS2-News participant CDN as CDN U-\u003e\u003eN: PrepareUpdateCurrentNewsMaster N--\u003e\u003eU: Upload URL U-\u003e\u003eN: HTTP PUT (zip) U-\u003e\u003eN: UpdateCurrentNewsMaster N-\u003e\u003eN: Build all patterns with hugo N-\u003e\u003eCDN: Place static content You can check the progress with the Progress model ( generated / patternCount ) and poll whether a long-running build has completed. Access Control for Article Data We explained that article data is pre-built in all patterns before being delivered. Malicious players must not be able to guess URLs and access content that has not yet been published. To avoid this problem, GS2-News implements access restrictions using cookies. When you obtain the URL of the currently active content, you also obtain the cookie information needed to access that URL. By setting that cookie in the browser and accessing the content URL, you can download the content. Cookie Expiration The cookie has an expiration; one hour after obtaining it, the cookie can no longer be used to access content. For players who play for a long time, please re-acquire the cookie. Downloading Web Content as a Zip In addition to accessing the HTML hosted by GS2-News via WebView, you can also download the entire HTML produced by GS2-News as a zip. Using this method, you can extract the downloaded zip content to local storage and view it in a browser, providing a smoother browsing experience and avoiding repeatedly downloading the same content. To determine whether the zip file should be re-downloaded, GS2-News exposes hash values for the template file and for the published content set determined by GS2-Schedule. By using these values, you can determine whether to re-download the zip file. Hash Description TemplateHash Hash of the uploaded template ZIP. Changes when the template itself is updated. ContentHash Hash of the set of published content determined by the current event status. Changes when events start or end. Script Triggers GS2-News does not provide script triggers. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. Template : Hugo template for displaying news Article : News articles in Markdown format In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. Transaction Actions GS2-News does not provide transaction actions. Implementation Examples Retrieving the Content URL The return value of GetContentsUrl includes a list of cookies, BrowserUrl (for viewing in WebView), and ZipUrl (for downloading as ZIP). After registering the obtained cookies in the WebView or HTTP client, access each URL. Example of Displaying in a WebView (Unity) Using unity-webview , set the obtained cookies on the WebView and then open BrowserUrl to display the news. foreach (var cookie in cookies) { webView.SetCookie(browserUrl, cookie.Key, cookie.Value); } webView.LoadURL(browserUrl); webView.SetVisibility(true); Retrieving a List of Article Data Each article holds Section , Title , Content , FrontMatter , etc. You can also use a configuration where you display the title list with your own UI and only display the selected article in a WebView. Deciding Whether to Re-download the Cache If you adopt the ZIP download approach, you can save TemplateHash and ContentHash locally and compare them against the values re-fetched on startup, to avoid unnecessary re-downloads of the ZIP. if (savedTemplateHash != domain.TemplateHash || savedContentHash != domain.ContentHash) { // Re-download } Detailed Reference GS2-News Reference","lang":"en","section":"microservices","summary":"Notification delivery feature\n","title":"GS2-News","url":"/microservices/news/"},{"content":"Manages game progression and quest progress. GS2-Quest is a microservice that manages on the server only the “entry” and “exit” of the in-game portion of the game (battles, stages, etc.). It is not involved in the internal logic of the in-game; it is responsible for processing that should be trusted by the server, such as cost consumption at start, granting rewards on clear, and evaluation of prerequisites. graph LR Start[\"Quest start StartAsync\"] --\u003e Battle[\"Run the in-game (client / dedicated server)\"] Battle -- Success --\u003e End1[\"Report quest end EndAsync(isComplete:true)\"] Battle -- Failure --\u003e End2[\"Report quest end EndAsync(isComplete:false)\"] End1 --\u003e Reward[\"Grant clear rewards\"] End2 --\u003e FailedReward[\"Grant failure rewards\"] Quests A quest is the basic unit of in-game play and is the entity you select when starting the in-game portion. A quest can have a cost required to attempt it and rewards earned by attempting it, and GS2-Quest accepts the start and end of a quest as APIs. In other words, GS2-Quest is not involved in the in-game content itself. Quest Challenge Cost You set the cost required to put a quest into the started state. Typically, you configure costs such as consuming stamina managed by GS2-Stamina or consuming items managed by GS2-Inventory. By configuring consume actions in consumeActions on the QuestModel , the costs are processed atomically as a transaction when Start is executed. Quest Verify Conditions By configuring verify actions in verifyActions on the QuestModel , you can perform additional condition checks when the quest starts. For example, you can express conditions that only check state without consuming anything, such as “the player must possess a specific item” or “a specific entry must be registered in GS2-Dictionary”. Quest Clear Rewards You can configure rewards obtained when the player attempts and clears a quest. Multiple types ( Contents ) can be prepared for rewards. Each Contents can have a weight for the lottery, and the reward pattern applied is determined according to that probability. Using this feature, you can set up a version of the quest where a rare monster appears with a certain probability and the rewards are more luxurious than usual. First Clear Reward You can configure an additional reward that is granted only the first time the quest is cleared. Set acquire actions in firstCompleteAcquireActions on the QuestModel . Reducing Clear Rewards If a monster that appeared in the quest was not defeated, or a treasure chest was missed, you can reduce the quest’s rewards. The quest start API responds with the maximum rewards obtainable within the quest, and the quest completion API reports the quantities actually obtained. By reporting fewer rewards in this report, the reward amount is reduced. If you attempt to report more rewards than the maximum, an error is returned. Quest Failure Rewards You can configure rewards obtained when the player attempts a quest but fails to clear it. They are configured in failedAcquireActions on the QuestModel . On failure, you can achieve processing such as refunding the stamina paid when starting the quest. Quest Prerequisites You can set the prerequisite that other quests must have been cleared before attempting a quest. By setting an array of quest names in premiseQuestNames on the QuestModel , the quest cannot be attempted unless all of the specified quests have been cleared. This allows you to chain quests together. Quest Challenge Period You can associate a GS2-Schedule event with a quest as its challenge period. The challengeable period is judged when the start API is executed; it is not judged at completion processing. Therefore, even if the period passes before the end is reported, there will be no situation where the quest reward cannot be received. Quest Group An entity that bundles multiple quests together. It is useful for managing quests grouped by chapter or world. Quest Group Challenge Period A quest group can also be associated with a GS2-Schedule event as its challenge period. When a challenge period is set on the quest group, the condition is applied to all quests within the group. When a challenge period is set on both the quest group and the quest, the quest can only be attempted when both events are active. Quest in Progress (Progress) When a quest starts, exactly one in-progress Progress is recorded on the server per user. The Progress holds the maximum rewards already determined by the lottery and a random seed generated on the server, which are used to verify the validity of the reward quantities reported. Since only one in-progress Progress can be held per user, if completion cannot be reported due to a disconnection or similar, you must discard it with DeleteProgress before starting another quest. When starting another quest, you can also start a new one while discarding the in-progress Progress by specifying force: true to StartAsync . Managing Clear Status When a quest is cleared, the name of that quest is recorded in CompletedQuestList . This is managed as a separate entity per quest group, allowing you to retrieve the clear status of a particular quest group in one go. The clear status is also used on the server to judge prerequisites, so when you need to modify it from outside, you must go through transaction actions. Script Triggers By configuring startQuestScript , completeQuestScript , and failedQuestScript on the namespace, you can invoke custom scripts at the timing of quest start, clear, and failure. The main event triggers and the script setting names that can be configured are as follows. startQuestScript : When a quest starts completeQuestScript : When a quest is cleared failedQuestScript : When a quest fails Scripts can make decisions such as overriding rewards or rejecting a quest start. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. QuestGroupModel : Quest groupings and their challenge periods QuestModel : Definition of costs and rewards In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. The main configuration items of the quest model are as follows. Item Description name Quest name contents Reward patterns selected by lottery ( completeAcquireActions and weight ) firstCompleteAcquireActions Reward granted only on the first clear failedAcquireActions Reward granted on failure consumeActions Resources consumed when starting verifyActions Prerequisite checks performed when starting premiseQuestNames Cleared quests that are required as prerequisites challengePeriodEventId GS2-Schedule event representing the challenge period Example master data in JSON: { \"version\": \"2022-02-15\", \"questGroupModels\": [ { \"name\": \"main\", \"metadata\": \"main-story\", \"quests\": [ { \"name\": \"quest-0001\", \"metadata\": \"intro\", \"contents\": [ { \"metadata\": \"normal\", \"completeAcquireActions\": [ { \"action\": \"Gs2Inventory:AcquireItemSetByUserId\", \"request\": \"{...}\" } ], \"weight\": 9 }, { \"metadata\": \"rare\", \"completeAcquireActions\": [ { \"action\": \"Gs2Inventory:AcquireItemSetByUserId\", \"request\": \"{...}\" } ], \"weight\": 1 } ], \"consumeActions\": [ { \"action\": \"Gs2Stamina:ConsumeStaminaByUserId\", \"request\": \"{...}\" } ], \"premiseQuestNames\": [] } ] } ] } Buff-Based Adjustment By integrating with GS2-Buff, you can apply buffs to a quest model’s completeAcquireActions , firstCompleteAcquireActions , failedAcquireActions , verifyActions , and consumeActions . You can flexibly adjust rewards, participation conditions, and consumption costs according to events and campaigns. You can implement experiences such as “1.5x quest rewards during the login campaign” or “half the challenge cost while a specific piece of equipment is equipped” without rewriting the master data. Transaction Actions GS2-Quest provides the following transaction actions. Consume action: Delete a quest progress ( Progress ) Acquire action: Create a quest progress ( Progress ) By using “Create quest progress” as an acquire action, you can safely run processes within a transaction that directly put a specific quest into a started state as a reward for a shop purchase or as a reward for completing a specific mission. This makes it easy to provide a seamless play experience such as immediately guiding the player to a special quest after they purchase a particular item. Implementation Examples Retrieving the List of Quest Groups Retrieving the List of Quest Models Retrieving Quest Clear Status Starting a Quest Retrieving the In-Progress Quest You can retrieve the maximum rewards determined when the quest started, which can be used for in-game clear presentation. Reporting the End of a Quest Report whether the quest was cleared with isComplete , and the actual quantities of rewards obtained with rewards . As long as the reported values are within the maximums returned by the in-progress Progress , those quantities of rewards are granted. Discarding the In-Progress Quest Use this for recovery when End could not be called due to a disconnection or similar. Other Features Branching Quests Under the normal specification, quests cannot be branched. If you want to implement a quest with two exits and which subsequent quest can be attempted depends on which exit was used, consider the following data structure. Quest Name Prerequisite Quest Quest1 Quest1a Phantom Quest1b Phantom Quest2a Quest1a Quest2b Quest1b This is a bit tricky, but a quest’s prerequisite quest can be set to a quest name that does not exist in the master data. Here, Quest1a / Quest1b have a quest named “Phantom” as their prerequisite, but the Phantom quest does not exist in the master data. Therefore, Quest1a / Quest1b are quests that can never be attempted directly. Quest2a / Quest2b have Quest1a / Quest1b as their prerequisite quests. In this state, configure the clear rewards of Quest1 to include “Mark Quest1a as cleared” and “Mark Quest1b as cleared”, and decide which of these rewards to give to the player based on which exit they used. The reason Quest1a / Quest1b exist is that quests that do not exist in the master data cannot be marked as cleared. graph TD Quest1 -- if use exit A --\u003e Quest1a Quest1 -- if use exit B --\u003e Quest1b phantom --- Quest1a phantom --- Quest1b Quest1a --\u003e Quest2a Quest1b --\u003e Quest2b linkStyle 2 stroke:#ccc,stroke-dasharray:4 linkStyle 3 stroke:#ccc,stroke-dasharray:4 class phantom pale class Quest1a pale class Quest1b pale Passing Parameters to Scripts via Config StartAsync / EndAsync accept a config parameter, which lets you pass arbitrary key-value pairs to the script when a script trigger runs. You can convey game-specific context such as the difficulty the player selected or which items they used. Resetting Clear Status By deleting CompletedQuestList , you can reset the clear status of a specific quest group. This is useful for implementing event re-runs or chapter new-game+ flows. Detailed Reference GS2-Quest Reference","lang":"en","section":"microservices","summary":"Progress tracking feature\n","title":"GS2-Quest","url":"/microservices/quest/"},{"content":"Warning GS2-Ranking2 has been released. Unless there is a special reason, please use GS2-Ranking2 for new use cases. Implements a ranking feature for competing on game scores and clear times. There are two types of rankings: “those where all participants compete on the same board” and “those where players compete against the scores of players they have subscribed to.” The former is called a global ranking, and the latter is called a scope ranking. Global Ranking Global ranking provides a ranking feature for competing against all players. GS2-Ranking can realize large-scale rankings involving hundreds of millions of players. Instead, ranking aggregation is not performed in real time; aggregation runs on a preconfigured cycle, and ranking is calculated based on those aggregated results. Category Set the type of ranking. For determining ranks, you must specify whether higher scores are better or lower scores are better. Aggregation Interval Set the interval at which ranking aggregation is performed. You can specify a minimum of 15 minutes and a maximum of 24 hours. A point to watch out for is that the interval you set here is not the interval from the start time of the previous aggregation, but the interval from the end time of the previous aggregation. Consider the case where aggregation takes 5 minutes and the first aggregation runs at 00:00. Aggregation start time Aggregation end time 00:00 00:05 00:20 00:25 00:40 00:45 Fixed Aggregation Time When the aggregation interval is set to 24 hours, there is a need to fix the time at which aggregation runs. To meet this need, a feature is provided that runs aggregation when a specified time is reached even if the aggregation cycle has not arrived. Suppose you set 24 hours for the aggregation interval and 5 AM for the fixed aggregation time. Aggregation start time Aggregation end time 2020-01-01 05:00 2020-01-01 05:05 2020-01-02 05:00 2020-01-02 05:05 2020-01-03 05:00 2020-01-03 05:05 Valid Score Range You can configure the range of values accepted as scores. This allows you to discard clearly inappropriate scores without performing the registration. In this case, no error is returned to the client in order to make it harder to investigate the boundary of invalid scores. Score Registration Period You can associate a GS2-Schedule event as the period during which score registration is accepted. Scores submitted outside the acceptance period are discarded. Aggregation does not run outside the score registration period, so there are no aggregation-related costs, but GS2-Schedule API calls do occur for the schedule check. Therefore, for rankings that will clearly never be referenced again, it is recommended to delete them from the master data. Ranking Data Access Period You can associate a GS2-Schedule event as the period during which ranking data can be accessed. This can be used in cases such as disabling score references after an event ends. Ranking Generations You can set a generation per category. By changing the generation, you can reset the registered content of the ranking without changing the category name. Score Updates When submitting a score, the server treats the most recently registered score as the valid score. Therefore, if you want to record only the best score in the ranking, the client must determine which score is better and decide whether to send the score or not. Retrieving Ranks You can retrieve the rank of a player with the specified user ID. This process attempts to return a rank that reflects the most recent state as much as possible. It computes the rank the player’s latest score would have within the latest aggregated results and returns that rank. Therefore, even if you obtain the rank immediately after a score update, you can get a value corresponding to the rank using the latest score even though the aggregation time has not arrived yet. Retrieving Rankings Around a Specified Score You can specify a score and retrieve the ranking around it. If there are a large number of identical scores, the specified score may not be placed exactly in the center of the list. Scope Ranking Scope ranking realizes rankings within a small set of players, such as a friends ranking. To realize this feature, a score bucket is prepared for each player. When a player updates their score, the data in the buckets of players who have subscribed to that player’s score is also updated. Each player computes the ranking using the scores in their own bucket. Master Data Management Ranking categories are defined in master data. CategoryModel : Ranking category settings (order, aggregation interval, fixed aggregation time, valid score range, registration period, viewable period, generation, score retention method, etc.) In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. Script Triggers GS2-Ranking does not provide script triggers. Transaction Actions GS2-Ranking does not provide transaction actions. Implementation Examples Registering a Score For convenience, this API can be called via ApplicationAccess. However, allowing arbitrary scores to be sent is a vulnerability. Therefore, if possible, configure this API so that it cannot be called from the client, and only accept score registration from trusted sources. For example, if you want to implement a ranking based on the number of items owned, it is safer to register the item ownership count as a score from a script that is triggered when an item is acquired in GS2-Inventory. Retrieving the Rank (Global) Retrieving the Ranking Subscribing to Another Player (Scope) Unsubscribing from Another Player (Scope) Retrieving the List of Subscribed Players Score Retention Settings For both global ranking and scope ranking, you can configure whether to hold a single score per user ID or multiple scores. You can choose whether only the most recently registered score is included in the ranking, or whether all registered scores are included. If all scores are included, the data volume tends to grow, which also affects GS2 usage fees. Unless there is a significant reason in your game system, we recommend configuring it so that only the most recently registered score is included in the ranking. Detailed Reference GS2-Ranking Reference","lang":"en","section":"microservices","summary":"Ranking feature\n","title":"GS2-Ranking","url":"/microservices/ranking/"},{"content":"Tip GS2-Ranking2 is, as its name suggests, a microservice that corresponds to version 2. For documentation on the previous version, see GS2-Ranking . Implements a ranking feature for competing on game scores and clear times. GS2-Ranking2 provides the following three modes. Global ranking Cluster ranking Subscription ranking Most of the ranking requirements a game needs should be satisfiable by one of these modes. Ranking Modes Global Ranking Global ranking provides a ranking feature for competing against all players. In GS2-Ranking2, only the top 1,000 players can participate in the ranking; the scores of players ranked 1,001 or lower are not registered in the ranking even when submitted. This is a significant change from the previous version, GS2-Ranking, which was provided with the ability to return accurate ranks among more than 100 million players. GS2-Ranking could handle large numbers of scores, but registration to the ranking did not occur until aggregation ran on a configurable interval between 15 minutes and 24 hours, and a cost proportional to the number of participants was incurred each time aggregation ran. GS2-Ranking2 was redesigned based on feedback from developers who used GS2-Ranking. Specifically, the following points were taken as important feedback for the redesign. In many use cases, it is sufficient to display only the top players Changes in rank should be reflected in the ranking immediately Ranking aggregation cost should not grow as the number of players grows As a result, as described above, only the top 1,000 players can participate in the ranking and players ranked 1,001 or lower are treated as “out of range”. In exchange, scores are reflected in the ranking immediately after they are registered, and no additional costs are incurred beyond the normal API request costs. Cluster Ranking Roughly the same as global ranking, with the only difference being that a separate ranking is created per cluster ID. By specifying a GS2-Guild guild ID as the cluster ID, you can implement rankings where guild members compete against each other. Cluster Participation Check In cluster ranking, by defining a cluster type, you can verify whether the player is a participant of the cluster before executing score registration. For example, when implementing a ranking that uses GS2-Guild guilds as clusters, by specifying Gs2Guild::Guild as the cluster type in the ranking mode settings, you can configure that when registering a score, the system first confirms that the player attempting to register a score to the guild specified by the cluster ID is registered as a member of that guild before performing the registration. Subscription Ranking A ranking feature whose specification is similar to GS2-Ranking’s scope ranking. By subscribing to other players, you can include the latest scores of those players in your own ranking board. This is used to realize rankings with strong inter-player asymmetry, such as friend rankings. Reflection Delay in Subscription Ranking When a score is registered, the score is asynchronously registered into the rankings of players subscribed to that player. This process usually completes within one second, but because it is asynchronous, there is a slight delay before the score is reflected. Seasons Each ranking can have a GS2-Schedule event associated with it as the period during which score registration is accepted. GS2-Schedule events can be configured to repeat, and each ranking is reset every time the event repeats. To realize this feature, GS2-Ranking2 has a season property on each ranking. Ranking results are stored per season, and past seasons’ results can be referenced at any time. Ranking Rewards In global ranking and cluster ranking, you can configure rank-based rewards. To configure a reward, set a rank threshold and reward content . If you specify 3 as the threshold, you can configure the reward for players ranked 1, 2, and 3. If you then specify 10, you can configure the reward for players ranked 4, 5, 6, 7, 8, 9, and 10. Rewards for Players Outside the Ranking By specifying 1001 as the threshold, you can configure rewards for players who are out of range. Configuring a ranking reward with threshold 1001 is optional; if not specified, out-of-range players cannot receive rewards. Receiving Rewards for Past Seasons Past seasons’ ranking rewards can be received at any time by calling the reward receipt API and specifying a past season number. Valid Score Range You can configure the range of values accepted as scores. This allows you to discard clearly inappropriate scores without performing registration. Period Settings Score Registration Period You can associate a GS2-Schedule event as the period during which score registration is accepted. Scores submitted outside the acceptance period are discarded. Ranking Data Access Period You can associate a GS2-Schedule event as the period during which ranking data can be accessed. This is useful when you want to disable score references after an event ends. Transaction Actions GS2-Ranking2 provides the following transaction actions. Verify action: Verify scores for global, cluster, and subscription rankings Consume action: Record ranking reward receipt history By using “Verify ranking score” as a verify action, you can safely set, within a transaction, restrictions such as products only purchasable by players who have recorded a score above a certain level, or quests that can only be attempted by such players. This makes it possible to reliably realize events such as special reward acquisition events limited to top-ranked players. Master Data Management By registering master data, you can configure the data and behaviors available in the microservice. The types of master data are as follows. RankingModel : Settings for the ranking mode and reward thresholds In addition to registering master data from the management console, you can also reflect data from GitHub or build a workflow that registers it from CI using GS2-Deploy. Implementation Examples Registering a Score For convenience, this API can be called via ApplicationAccess. However, allowing arbitrary scores to be sent is a vulnerability. Therefore, if possible, configure this API so that it cannot be called from the client, and only accept score registration from trusted sources. For example, if you want to implement a ranking based on the number of items owned, it is safer to register the item ownership count as a score from a script that is triggered when an item is acquired in GS2-Inventory. Global Ranking Cluster Ranking Subscription Ranking Retrieving the Rank Global Ranking Cluster Ranking Subscription Ranking Retrieving the Ranking Global Ranking Cluster Ranking Subscription Ranking Receiving Ranking Rewards Ranking rewards can be received by players who fall within the configured reward threshold by calling the API. The receipt is executed as a transaction, and the configured acquire actions are evaluated in order. To receive rewards for a past season, specify the target season number in season . Global Ranking Cluster Ranking Detailed Reference GS2-Ranking2 Reference","lang":"en","section":"microservices","summary":"Ranking feature","title":"GS2-Ranking2","url":"/microservices/ranking2/"},{"content":"This feature can be used for low-latency, high-frequency communication to allow game players to play against each other. GS2 typically charges by the number of API requests, but for this service, once the game server is up and running, a fee is charged for the time the game server is running and for communication capacity. There is no charge per number of communications. graph TD Match[\"Lobby established by GS2-Matchmaking\"] --\u003e Want[\"Request a room with RoomWant\"] Want -- Allocated from hot standby --\u003e Warm[\"Warm Start (1 to 3 seconds)\"] Want -- New launch --\u003e Cold[\"Cold Start (40 to 60 seconds)\"] Warm --\u003e Connect[\"Player connects\"] Cold --\u003e Connect Connect --\u003e Play[\"In-game communication via packet relay\"] Play -- No communication for 1 minute or 3 hours elapsed --\u003e Shutdown[\"Room terminated\"] Server Type Currently, GS2-Realtime only provides packet relay functionality. This is based on the ability to send a message to a game server, which will then broadcast the message to other players. It also has the ability to specify a player ID and deliver the message only to the specified player. The SDK does not include features such as RPC or object synchronization, only the ability to send and receive simple binary data. Binary encoding of the payload is the responsibility of the application, so you can adopt any encoding such as Protocol Buffers / FlatBuffers / MessagePack. Unreal Engine Dedicated Server Hosting We are looking into the possibility of allowing developers to host a dedicated server built with the Unreal Engine. We have not yet decided when this feature will be available. If you have a strong need and would like to proceed with development under a paid support contract, we can work out a schedule, so please consult us. Server Specs You can set the performance of the server. The performance will make a difference in the price per minute. We have confirmed that the cheapest realtime1.nano can have 8 players send messages to each other 3 times per second. The Unreal Engine Dedicated Server hosting we are considering will have higher requirements. Unreal Engine Dedicated Server is not recommended for projects where cost efficiency, not development efficiency, is paramount. The server spec is configured per Namespace, by specifying an identifier such as realtime1.nano in the serverSpec field. Life Cycle A game server is not scheduled to start until it receives a startup request. At this point, GS2 will prepare a hot standby for game servers that receive frequent startup requests. Therefore, allocation can be expected immediately after the startup request is received, but for small-scale games where startup requests do not occur frequently, it takes time from the startup request to the actual allocation. We refer to the case where the allocation is done from a hot standby as a warm start, and the case where the allocation is done by starting a new server as a cold start. The estimated time required for cold start allocation is about 40 to 60 seconds, while the time required for warm start allocation is assumed to be 1 to 3 seconds. For titles of a size that do not generate frequent startup requests and where cold start time is unacceptable, Hot Standby can be provided on the assumption that a fixed monthly fee will be charged. We accept contracts for hot standby with a minimum of 5 units. We cannot guarantee that cold starts will not occur even if you have a hot standby contract or in situations where frequent startup requests are occurring. Cold starts can occur if server startup requests are made faster than hot standby is available or if the game server is being upgraded. Therefore, please design your system with the worst-case scenario of a cold start in mind. Types of Start Type Time Required Description Warm Start 1 to 3 seconds Immediate allocation from hot standby Cold Start 40 to 60 seconds Launches a new server process Room Termination Conditions A launched room will be terminated under the following conditions: If no one connects within 5 minutes after the room is created If all players in the room have been silent for 1 minute If the maximum room lifetime of 3 hours is reached In addition, you can explicitly call RoomShutdown to terminate the room immediately. Note that the same termination process applies to hot standby rooms as well, but hot standby uptime is not added to your usage charges. Connecting to a Room GS2-Realtime uses the following flow for connection. sequenceDiagram participant Player participant Realtime as GS2-Realtime participant Server as GameServer Player -\u003e\u003e Realtime: Room(roomName).Model() Realtime --\u003e\u003e Player: IpAddress / Port / EncryptionKey Player -\u003e\u003e Server: RelayRealtimeSession.ConnectAsync() Server --\u003e\u003e Player: Connection established Note over Player,Server: After this, communicate directly with the game server over WebSocket The connection information consists of the following three items: IpAddress : IP address of the game server Port : Port number to connect to EncryptionKey : Encryption key for the message payload When connecting, you pass the access token and the initial profile value of the player. Profile Relay servers not only forward received messages to other players, but also allow each player to have profile data. When a new player connects to the game server, they will receive profile data for all other participating players. Storing basic player information simplifies the process when a new player connects. When a player updates their profile, the information is sent to other players, so it can be used as a substitute for sending a message. However, it is not optimal in terms of communication efficiency to use high-frequency messaging via profile updates, since the entire payload is sent and received when a profile is updated. A profile can be encoded as a binary payload in any format. It is suitable for storing snapshots of player character information, equipment, level, in-game currency, etc. Event Handling You can set the following event handlers on RelayRealtimeSession . Handler Trigger OnJoinPlayer When another player joins the room OnLeavePlayer When another player leaves the room OnRelayMessage When a relay message is received from another player OnUpdateProfile When another player updates their profile OnError When a protocol error occurs OnGeneralError When a communication error occurs OnClose When the connection to the game server is closed Extended versions including MessageMetadata (such as OnRelayMessageWithMetadata ) are also provided for each event, allowing you to also retrieve metadata about the message. Push Notifications The main push notifications you can configure and their settings are as follows. createNotification : Notifies when a room is assigned Enabling enableTransferMobileNotification also allows mobile push forwarding to offline devices. By notifying all members gathered by GS2-Matchmaking of the room assignment, you can announce in real time that the match is ready. Master Data Operation GS2-Realtime does not require master data. It can be operated solely with namespace settings (server type, server spec, and push notification settings). Transaction Actions GS2-Realtime does not provide transaction actions. Integration with Other Microservices GS2-Realtime is typically used in combination with the following microservices rather than on its own. Service Purpose GS2-Matchmaking Match opponents, then call RoomWant once a match is formed GS2-Gateway Use as the route for the createNotification push notification GS2-Account Issue player access tokens Example Implementation Obtaining connection information for the game server Specify the room name to retrieve the connection information. If the room was prepared via matchmaking through RoomWant , specify its roomName . Connect to game server Handling connections from other players Handling disconnections of other players Handling messages from other players Handling profile updates of other players Handling disconnects from game server Update profile Send broadcast message If targetConnectionIds is omitted, the message is delivered to every player in the room except yourself. Send unicast message Specify the ConnectionId of the target player in targetConnectionIds . The ConnectionId can be obtained from events such as OnJoinPlayer . Design Notes Designing the binary payload GS2-Realtime simply relays binary data as-is without interpreting its content. Therefore, the following aspects must be designed on the application side: A header to identify message types (for example, putting an opcode in the first byte) Serialization format (Protocol Buffers / FlatBuffers / MessagePack, etc.) Ordering guarantees if needed (assign sequence numbers in the application layer when required) Cheat Prevention Since the relay server does not interpret the payload contents, it cannot detect cheating itself. For calculations such as rating, results are determined by majority vote. Detailed Reference GS2-Realtime Reference","lang":"en","section":"microservices","summary":"Real-time communication feature\n","title":"GS2-Realtime","url":"/microservices/realtime/"},{"content":"Provides functionality to manage schedules for in-game events and similar activities. On its own, GS2-Schedule only manages event duration information; reward granting, purchase restrictions, and similar processing are realized by combining it with other microservices. Nearly all game-element microservices such as GS2-Showcase / GS2-Exchange / GS2-LoginReward / GS2-Mission are designed on the premise of cooperating with event durations, making it the core microservice when conducting limited-time operations. Event Duration There are two types of event duration. The first is an “absolute period,” where all players share the same duration. The second is a “relative period,” where the duration differs per player. graph TD Event[\"Event\"] Event --\u003e Absolute[\"Absolute period (scheduleType = absolute)\"] Event --\u003e Relative[\"Relative period (scheduleType = relative)\"] Absolute --\u003e AbsoluteSample[\"e.g. New Year event from Jan 1 to Jan 3\"] Relative --\u003e RelativeSample[\"e.g. 7 days from first play, 24 hours after the first boss defeat\"] Absolute Period This duration type is used for cases like “Hosting a New Year’s event from January 1st to January 3rd.” Since all players share the same active period, you specify absoluteBegin / absoluteEnd in the master data. Relative Period This duration type is used for cases where the event period differs per player, such as “One week from game start” or “24 hours after defeating a boss for the first time.” To implement relative periods, there is a mechanism called “Triggers.” After executing a trigger, the specified duration (ttl) is treated as the event’s active period. Gs2Schedule:TriggerByUserId Action Types of Trigger Activation Methods When pulling a trigger, there are multiple ways to specify the event period if the trigger has already been pulled. Restart the trigger (renew) Extend the trigger (extend) Do nothing (drop) Expires at the event’s repeat cycle end date/time (repeatCycleEnd) Expires at the next repeat cycle start date/time (repeatCycleNextStart) Expires at the absolute period event’s end date/time (absoluteEnd) repeatCycleEnd / repeatCycleNextStart / absoluteEnd are methods that automatically adjust the expiration date based on the event’s repeat settings or absolute period. If a trigger is pulled at 00:00 on January 1, 2020 and a 7-day relative period event is started, the behaviors when the trigger is pulled again at 00:00 on January 3, 2020 are as follows. Method Event End Date/Time renew January 10, 2020 00:00 Adds 7 days to the trigger activation time of January 3, 2020 00:00 extend January 14, 2020 00:00 Adds 7 days to the expiration of the existing trigger, January 7, 2020 00:00 drop January 7, 2020 00:00 Keeps the existing trigger as is Repeat Settings For both absolute and relative periods, by combining RepeatSetting you can express repeating schedules such as “active only on specific days of the week or hours” or “switching active/inactive on a multi-day cycle.” The repeat types you can configure are as follows. repeatType Description always Always active during the period daily Active every day only between the specified hours ( beginHour / endHour ) weekly Active every week only between the specified days of the week ( beginDayOfWeek / endDayOfWeek ) monthly Active every month only between the specified days of the month ( beginDayOfMonth / endDayOfMonth ) custom Repeats active/inactive on an arbitrary cycle ( anchorTimestamp / activeDays / inactiveDays ) The custom type can express arbitrary repeat cycles such as “3 days active, 4 days inactive from an anchor date/time,” which is useful for designing irregular permanent events. Retrieving repeat schedule state For events with repeat settings, you can obtain the start and end date/times of the current and previous repeat cycles as RepeatSchedule . This allows you to aggregate how many times rewards have been received in the current cycle, or to display the remaining time until the next cycle. Transaction Actions GS2-Schedule provides the following transaction actions: Verify actions: verify that the event is in its active period, verify that the event is outside its active period, verify that a trigger has been pulled, verify that a trigger has not been pulled, verify the elapsed time since a trigger was pulled Consume actions: delete a trigger Acquire actions: execute a trigger, extend trigger duration By using “verify event duration” as a verify action, it is possible to safely set restrictions within a transaction, such as products that can only be purchased during a specific event period or a limited-time exchange. Additionally, by using “execute trigger” as an acquire action, it facilitates the dynamic control of game experiences, such as starting a personalized limited-time event (relative period) for a player upon completing a quest or acquiring an item. Master Data Management Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: EventMaster : Event duration and repeat settings The following is a JSON example of master data. { \"version\": \"2019-03-31\", \"events\": [ { \"name\": \"newyear-2026\", \"metadata\": \"New Year event\", \"scheduleType\": \"absolute\", \"absoluteBegin\": 1735660800000, \"absoluteEnd\": 1735920000000, \"repeatType\": \"always\" }, { \"name\": \"tutorial-bonus\", \"metadata\": \"Limited to 7 days from first play\", \"scheduleType\": \"relative\", \"relativeTriggerName\": \"tutorial-clear\", \"repeatType\": \"always\" } ] } Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Example Implementation Pulling a trigger Trigger pulling cannot be performed via the game engine SDK. Please implement it via a script in GS2-Account at account creation, or by pulling a trigger as a clear reward in GS2-Quest, for example. Obtaining a list of current events Only events that are active from the current player’s perspective are returned. This includes events whose absolute period is active, or whose relative period trigger has been pulled and is still within its expiration. Obtaining information for a specific event Specify an event name to obtain its duration and repeat settings. Setting isInSchedule to true returns only events currently in progress; setting it to false allows you to reference all events registered in the master data. Obtaining a list of triggers You can obtain a list of relative-period triggers pulled for the player, along with their expiration dates. Retrieving repeat schedule state Obtain information for the current repeat cycle of an event with repeat settings. You can check the number of repeats, the start and end date/times of the current cycle, and the end date/time of the previous cycle. Detailed Reference GS2-Schedule Reference","lang":"en","section":"microservices","summary":"Event scheduling feature\n","title":"GS2-Schedule","url":"/microservices/schedule/"},{"content":"GS2-Script is a Lua-based script execution environment that runs custom logic on the server side in response to events from GS2 microservices. Each GS2 microservice provides a mechanism called “script triggers” that runs a script before or after a specific API call. By linking scripts written with GS2-Script to these triggers, you can execute on the server side game-specific validation logic, data processing, and external system integration that cannot be achieved with the standard features of each service. Because client-side logic is at risk of tampering, in many cases you want fraud prevention and audit-critical processing to run on the server side. With GS2-Script, you can write and operate such server logic within the GS2 fully-managed environment. Lua scripts The language used to write scripts is Lua . Lua is a lightweight scripting language with a strong track record in the game industry, with simple syntax and high execution performance. Scripts can be registered either by directly uploading a string, or by retrieving files via integration with a GitHub repository. By using GitHub integration, you can manage script change history in Git and operate with pull request-based review. Script triggers In the namespace settings of each microservice, you can specify scripts to be run before or after specific API processing. The execution timing of scripts is broadly divided into two types. graph LR Request[\"API Request\"] --\u003e Pre[\"Pre-processing Script (Synchronous)\"] Pre --\u003e Process[\"GS2 Standard Processing\"] Process --\u003e Done[\"Completion Notification Script (Asynchronous)\"] Process --\u003e Response[\"API Response\"] Pre-processing script (synchronous execution) A script that is executed synchronously immediately before the API processing. The script’s execution result can transform the request parameters, or abort the processing itself (by raising an exception). While this affects response time, it is useful when you want to dynamically determine or modify request content on the server side. Example: Setting triggerScriptId of GS2-Account’s createAccountScript causes the script to run before the account creation API, allowing control such as rejecting creation under specific conditions. Completion notification script (asynchronous execution) A script that is executed asynchronously after the API processing has completed. It does not affect response time, and can safely perform logging, statistics collection, and external service integration. Example: Setting doneTriggerScriptId of GS2-Account’s createAccountScript causes the script to run after account creation succeeds, which can be used for purposes such as sending a new user creation event to an external analytics platform. Script execution model Script execution has a time limit set by default, and overly long scripts result in errors. Script execution time is included in the response and tallied as execution cost. Exceptions raised within a script propagate as exceptions of the entire API call. If an exception occurs in a pre-processing script, the GS2 standard processing is not executed. Calling GS2 APIs from scripts GS2 APIs can be called directly from within scripts. You can compose logic that spans multiple microservices within a script, such as checking item counts in GS2-Inventory before processing in GS2-Account, or checking remaining stamina in GS2-Stamina before determining a mission achievement in GS2-Mission. The script execution context also receives the access token of the user who initiated the API call, allowing server APIs to be called in the context of an authenticated player. Amazon EventBridge Integration Amazon EventBridge can be specified as the destination for completion notifications instead of a GS2-Script script. By sending events to EventBridge, GS2 events can be integrated with AWS services such as AWS Lambda, or with SaaS event-driven workflows, making it easy to integrate with external systems. By using GS2-Script for processing that completes within GS2 and EventBridge for broader integration with external systems, you can achieve simple and scalable operation. Master Data Management GS2-Script does not have the concept of master data; the scripts themselves are managed as configuration data. Scripts can be registered and updated directly from the management console, or written as GS2-Deploy templates ( Type: GS2::Script::Script ) for a workflow that automatically applies them from CI. Transaction Actions GS2-Script does not provide transaction actions. However, by calling GS2 APIs from within scripts, you can indirectly trigger transactions of each microservice. Example Implementation GS2-Script is a microservice centered on management APIs. No dedicated Domain class is provided in the game engine SDKs (Unity / Unreal Engine). Because script registration, updates, and execution involve server-side and namespace configuration operations, instead of calling them directly from the game client, we recommend operating via one of the following means. Management console GS2 CLI General-purpose SDKs for various languages (C# / Go / Python / TypeScript / PHP / Java) Template management via GS2-Deploy For details on each SDK, see the corresponding reference page. Linking scripts to microservices When linking a script to an event trigger of a microservice, the target service’s namespace settings reference it. In practice, you either configure it directly from the management console, or describe it in a GS2-Deploy template to manage the script linking via CI/CD. Below is an example of setting up scripts for both “before account creation” ( TriggerScriptId ) and “account creation completion notification” ( DoneTriggerScriptId ) in CreateAccountScript of GS2-Account. GS2TemplateFormatVersion: \"2019-05-01\" Resources: Script: Type: GS2::Script::Script Properties: NamespaceName: namespace-0001 Name: createAccount Script: | local result = { permit = true } return result AccountNamespace: Type: GS2::Account::Namespace Properties: Name: account-namespace CreateAccountScript: TriggerScriptId: !GetAttr Script.Item.ScriptId DoneTriggerTargetType: gs2_script DoneTriggerScriptId: !GetAttr Script.Item.ScriptId DependsOn: - Script The script is registered in advance, and the namespace references it by GRN. By declaring resource dependencies with DependsOn , you can guarantee the order so that the script is created first, then the namespace that references it. Detailed Reference Reference of GS2-Script","lang":"en","section":"microservices","summary":"Lua script execution environment\n","title":"GS2-Script","url":"/microservices/script/"},{"content":"This feature classifies players by player skill and enables matchmaking with players of similar skill. GS2-Matchmaking has a matchmaking function based on rating values, but it does not support the recently increasing system of ranking players over the course of a season, which can last from a few weeks to a few months in real time. This microservice can be used to realize a game cycle in which players repeatedly play against each other to achieve a high tier during a season, considering a defined period of time as a season. Therefore, the indicator of strength in this feature is not a rate value, but is expressed by which tier the player belongs to. graph TD Match[\"GS2-Matchmaking match established\"] --\u003e Session[\"Create MatchSession\"] Session --\u003e Ballot[\"Each player obtains a ballot (Ballot / SignedBallot)\"] Ballot --\u003e GamePlay[\"Gameplay\"] GamePlay --\u003e Vote[\"Vote / VoteMultiple Submit rankings\"] Vote --\u003e Aggregate{\"Result determined by majority\"} Aggregate -- determined --\u003e Calc[\"Calculate point change (based on TierModel)\"] Calc --\u003e Experience[\"Apply points / rank to GS2-Experience\"] Aggregate -- split --\u003e Skip[\"End without aggregation\"] Tiers Tiers generally start at Bronze and go up through Silver, Gold, Platinum, and so on as you win more games. To move up a tier, you play against other players in the same tier, and if your points, which vary depending on your ranking, exceed a threshold, you move up to the next tier. If you lose the match, your points may decrease, and if your points fall below the threshold, you may move down to the previous tier. Tier model configuration items Each tier is defined as a TierModel , and the following parameters control point variation and behavior on promotion. Item Description metadata Free description such as tier name (Bronze/Silver/Gold, etc.) entryFee Points consumed when joining a game. Used for designing difficulty in which players cannot be promoted without consecutive wins minimumChangePoint Amount of points subtracted when finishing in last place maximumChangePoint Amount of points added when finishing in first place raiseRankBonus Bonus points granted when ranking up. Useful for preventing chattering (immediate demotion right after promotion) Matches across tiers In rating matches, matchmaking rules should in principle consist of the same tier. However, when matchmaking includes players from the previous and next tiers due to a lack of players or other reasons, the amount of point fluctuation is determined based on the minimum and maximum fluctuation and ranking of the tier to which each player belongs. There is no mechanism to grant bonus points when a player in a lower tier beats a player in a higher tier, or vice versa. Rather than trying to craft adjustments to pit players of fundamentally different strengths against each other, it is recommended to design tier thresholds so that each tier retains at least enough players to make gameplay viable. Points Range of variation For each tier, you can set the amount of points subtracted when finishing last and the amount of points added when finishing first. For intermediate ranks, the amount of points added or subtracted is determined by dividing equally by the number of patterns in the reported rankings. Entry Fee Depending on the tier, you can configure points to be consumed in order to participate in a game. This allows you to express conditions in which consecutive wins are required to advance up a tier. The entry fee is paid when obtaining the ballot used to report the game results to the server. Rank Up Bonus Bonus points can be added when a player is promoted to a higher rank by adding points. This prevents chattering where the player is demoted again immediately after promotion. User Data Management GS2-SeasonRating does not manage points and ranks itself. Actual user data management is done using GS2-Experience. As season master data, specify the GS2-Experience experience model that manages the season’s points, and specify the season model ID as the property ID; the experience value manages the points and the rank manages which tier the player belongs to. In other words, the amount of point variation is managed by GS2-SeasonRating master data, but the thresholds that determine rank based on points, and the user data of which tier a player belongs to, are managed by GS2-Experience. This allows you to use advanced features such as the rank value verification provided by GS2-Experience for exchange processes that grant items to players of a specific rank at the end of the season. graph LR SeasonModel[\"SeasonModel (GS2-SeasonRating)\"] -- \"experienceModelId\" --\u003e ExpModel[\"ExperienceModel (GS2-Experience)\"] ExpModel -- \"rank thresholds\" --\u003e Status[\"Player rank status (stored in GS2-Experience)\"] Vote[\"Vote result determined\"] -- \"point add/subtract\" --\u003e Status Match Sessions To conduct a rating match, you must first create a match session resource in GS2-SeasonRating. GS2-Matchmaking has an integration feature that creates a match session with the name of the gathering when matchmaking is established. Unless there is a particular reason not to, please create match sessions in this way. Expiration of a match session Match sessions can have an expiration in seconds, up to a maximum of 24 hours. Results must be voted on within this period, and if 5 minutes have passed since the first vote and not all votes have been cast, the results are aggregated at that point. Voting on results Once matchmaking is complete, each player retrieves a ballot from the match session. The ballot is used to vote on the results. The vote contents include a list of user IDs of the players who participated in the match and their rankings. Ballot signing When you obtain a Ballot , GS2 issues it as a SignedBallot with a signature. The signature is generated by the GS2-Key specified in keyId , and signature verification is performed on the server side at the time of voting, so the vote contents cannot be tampered with. Voting multiple ballots per match (VoteMultiple) For cases in which a single player must obtain and submit ballots for all participants together (such as a single-player game where the results against CPUs are submitted), use VoteMultiple . You can send multiple SignedBallot s at once. Vote result fragmentation When the server tries to take a majority vote of the accepted votes, if the result is a tie and the final result cannot be determined, no rate calculation is performed. This makes it difficult to determine the correct rate value in a 1vs1 game. To solve this problem, you may need to devise a workaround such as matchmaking a third player who is not directly involved in the game behind the scenes and having that player vote from a third-party perspective. Script Triggers GS2-SeasonRating does not provide script triggers. Transaction Actions GS2-SeasonRating does not provide transaction actions. Point and rank changes are internally reflected via the transaction actions of GS2-Experience. To distribute rewards to players above a specific rank after the season ends, a common implementation is to combine the exchange process of GS2-Exchange with the VerifyRankAction of GS2-Experience. Master Data Operation Registering master data allows you to configure data and behaviors available to the microservice. Master data types include: SeasonModel : The tiers included in a season, and the linked GS2-Experience experience model TierModel : Point variation, entry fee, and rank up bonus for each tier Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. The following is a JSON example of master data. { \"version\": \"2023-04-05\", \"seasonModels\": [ { \"name\": \"season-0001\", \"metadata\": \"Season 1\", \"experienceModelId\": \"grn:gs2:{region}:{ownerId}:experience:experience-0001:model:season\", \"tiers\": [ { \"metadata\": \"Bronze\", \"raiseRankBonus\": 100, \"entryFee\": 0, \"minimumChangePoint\": 10, \"maximumChangePoint\": 30 }, { \"metadata\": \"Silver\", \"raiseRankBonus\": 150, \"entryFee\": 10, \"minimumChangePoint\": 20, \"maximumChangePoint\": 40 } ] } ] } Example Implementation Get current points and rank Use the GS2-Experience API to obtain the status. Specify the values specified in the season master data for “NamespaceName” and “ExperienceName,” and specify the season model ID for “PropertyId.” Create a match session Creating a match session cannot be handled by the game engine SDK. Please use the GS2-Matchmaking integration feature. By setting a script that invokes match session creation in GS2-SeasonRating as the script triggered when matchmaking is established in the GS2-Matchmaking namespace settings, a corresponding session can be automatically generated upon matchmaking completion. Retrieve a ballot Vote Vote multiple ballots at once Use this when one player submits ballots on behalf of all participants, for example for CPU battle results. Detailed Reference GS2-SeasonRating Reference","lang":"en","section":"microservices","summary":"Season rating feature","title":"GS2-SeasonRating","url":"/microservices/season_rating/"},{"content":"This feature can be used when you want to distribute in-game items through out-of-game merchandising, real events, SNS campaigns, collaboration campaigns, and so on. The same mechanism can handle codes printed on paper packaging or QR codes, as well as strings distributed via email/SNS. However, some platformers do not allow the implementation of this feature, so please check the platformer’s guidelines before adoption. Types of Serial Codes There are two types of serial codes: Serial Key: A code that cannot be reused once redeemed Campaign Code: A code that can be shared and redeemed by multiple players graph TD SerialCode[\"Serial code\"] SerialCode --\u003e SerialKey[\"Serial key One use per player\"] SerialCode --\u003e CampaignCode[\"Campaign code Shared by multiple players\"] SerialKey --\u003e SerialKeyUse[\"RPCLP-FP7N-NCDMJ-FLVA-IRI4\"] CampaignCode --\u003e CampaignCodeUse[\"NEWYEAR2026\"] Serial Key A code that cannot be used again once it has been redeemed. Serial keys are issued in a format such as “RPCLP-FP7N-NCDMJ-FLVA-IRI4” and the data length cannot be changed. Information about the campaign is also included in the serial key, so when using a serial key you only need to specify the namespace. Campaign Code A code in which the operator can freely set a string that is easy for humans to remember, such as “Halloween2025” or “SUMMER.” It is intended that many players share and redeem the same code. Unlike serial keys, which are issued in association with a campaign, a campaign code uses the name of the campaign itself as the redeemable code. Campaign Both serial keys and campaign codes belong to a campaign. A campaign has the following settings: name : Campaign name (also used as the campaign code) metadata : Arbitrary metadata enableCampaignCode : Whether to enable the campaign code (redemption using the campaign name itself) By associating a campaign with a GS2-Schedule event, you can set its valid period. Validation of the valid period can be achieved by combining transaction actions. Issuing serial keys Serial keys are issued by specifying the target campaign and the number to issue and running the issue process. The issue process runs as an asynchronous job, and progress can be checked through IssueJob . The list of issued serial keys can be downloaded in CSV format. For uses such as printing on packaged merchandise, hundreds of thousands of keys can be issued at once. Serial Key Status A serial key has the following states: Status Description ACTIVE Available for the player to use USED Already used (cannot be reused) INACTIVE Deactivated by the operator ACTIVE is the state in which the player can actually use the key, and it becomes USED once used. If the operator deactivates the key, it becomes INACTIVE . Transaction Actions GS2-SerialKey provides the following transaction actions: Verify actions: verify serial code validity, verify that a serial code belongs to a specified campaign Consume actions: mark a serial code as used Acquire actions: revert a serial code to unused (for cancellation), issue a serial code By using “Issue serial code” as an acquire action, you can safely complete processes within a transaction such as automatically issuing and gifting a unique serial code (transferable to others) per player upon completing a specific in-game mission or as a reward for a top ranking. This facilitates measures that encourage fan interaction outside the game and gift-giving among players. Limit on the number of redemptions by code By default, campaign codes can be redeemed an unlimited number of times. Typically there are requirements such as “do not allow redemption again once redeemed” or “do not allow redemption for a certain period of time,” and for both campaign codes and serial keys there may be various requirements such as “limit the total number of redemptions within the same campaign.” GS2-SerialKey does not provide such limit functions; it purely provides a function that determines whether the entered serial key is valid. Therefore, GS2-SerialKey itself has no rewards granted at the time of redemption. An example implementation when using a serial key is shown below. actor Player participant \"GS2-Exchange#Rate\" participant \"GS2-SerialKey#SerialKey\" participant \"GS2-Limit#Counter\" participant \"GS2-Inventory#Item\" Player -\u003e \"GS2-Exchange#Rate\" : Exchange \"GS2-Exchange#Rate\" -[#f00]-\u003e \"GS2-SerialKey#SerialKey\" : Use \"GS2-Exchange#Rate\" -\u003e \"GS2-Limit#Counter\" : Increase \"GS2-Exchange#Rate\" -\u003e \"GS2-Inventory#Item\" : Acquire \"GS2-Exchange#Rate\" -\u003e Player GS2-Exchange defines the reward obtained when a serial key is used, and GS2-Limit applies a redemption count limit, preventing items from being obtained multiple times. When composing rewards, complex requirements can be realized by combining multiple microservices in a transaction, such as campaign period checks via GS2-Schedule or item granting via GS2-Inventory. Master Data Management Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: CampaignModel : Definition of a campaign (the parent group of serial keys / campaign codes) The following is a JSON example of master data. { \"version\": \"2019-08-19\", \"campaigns\": [ { \"name\": \"newyear-2026\", \"metadata\": \"New Year campaign\", \"enableCampaignCode\": true }, { \"name\": \"package-promo\", \"metadata\": \"For package insert (campaign code disabled)\", \"enableCampaignCode\": false } ] } Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Example Implementation Using a serial key It is not recommended to process the use of a serial key directly via this API. By using the serial key through a service such as GS2-Exchange, the use of the serial key, granting of rewards, and check of redemption count limits can be handled as a single transaction. Getting serial key information Specify a serial key code to check which campaign it belongs to and its current state ( ACTIVE / USED / INACTIVE ). This can also be used to display error messages such as “the entered code has already been used” on a redemption screen. Getting campaign information Get the definition of a specific campaign (metadata, whether the campaign code is enabled, etc.). Detailed Reference GS2-SerialKey Reference","lang":"en","section":"microservices","summary":"Serial code feature\n","title":"GS2-SerialKey","url":"/microservices/serial_key/"},{"content":"This feature is used to sell products in the game. The difference from GS2-Exchange is the existence of a showcase. DisplayItems can be placed on a showcase, and you can configure the cost required to purchase a DisplayItem and the reward obtained when purchasing it. There are two types of showcases: the “Standard Showcase,” on which fixed DisplayItems are placed, and the “Random Showcase,” on which the displayed contents are randomly drawn at regular intervals. graph TD Master[\"Master data\"] --\u003e Showcase[\"Standard showcase (ShowcaseModel)\"] Master --\u003e RandomShowcase[\"Random showcase (RandomShowcaseModel)\"] Showcase --\u003e DisplayItem[\"DisplayItem (SalesItem / SalesItemGroup)\"] RandomShowcase --\u003e RandomDisplayItem[\"RandomDisplayItem (stock / weight)\"] Player[\"Player\"] -- Buy --\u003e DisplayItem Player -- RandomShowcaseBuy --\u003e RandomDisplayItem DisplayItem -- \"consumeActions / acquireActions\" --\u003e Transaction[\"GS2-Distributor execute transaction\"] RandomDisplayItem -- \"consumeActions / acquireActions\" --\u003e Transaction Standard Showcase On a standard showcase, all of the specified DisplayItems are placed. There are two types of DisplayItem: “SalesItem” and “SalesItemGroup.” SalesItem A SalesItem can be configured with the cost required to purchase it and the reward obtained when purchased. A SalesItem expresses its behavior using the following three kinds of actions. Item Description verifyActions Verify actions for purchase conditions. Verifies the state of the specified microservice, and rejects the purchase if the conditions are not met. consumeActions Actions consumed at the time of purchase. Currency in GS2-Money2 or items in GS2-Inventory, etc., are consumed as the cost. acquireActions Actions to acquire at the time of purchase. Distributes rewards to any microservice such as GS2-Inventory / GS2-Experience / GS2-Lottery. SalesItemGroup A SalesItemGroup is a mechanism in which the SalesItem being sold changes depending on the number of purchases. A SalesItemGroup can contain multiple SalesItems, and for all but the last item in the list, a GS2-Limit counter increment must be set as the cost. When a SalesItemGroup is placed on a showcase, the system determines whether the internal SalesItems are purchasable, and the first SalesItem determined to be purchasable is displayed. By using this feature, you can sell an item at half price for first purchases only, realize items whose price rises with each purchase, or add a bonus on the 10th purchase, and so on. graph LR Buy[\"Purchase request\"] --\u003e Check1{\"SalesItem 1 (first-time only)\"} Check1 -- Purchasable --\u003e Sell1[\"Sell SalesItem 1\"] Check1 -- Already purchased --\u003e Check2{\"SalesItem 2 (2nd to 9th time)\"} Check2 -- Purchasable --\u003e Sell2[\"Sell SalesItem 2\"] Check2 -- Limit reached --\u003e Check3{\"SalesItem 3 (10th-time bonus)\"} Check3 -- Purchasable --\u003e Sell3[\"Sell SalesItem 3\"] Random Showcase On a random showcase, a specified number of DisplayItems are randomly drawn from those specified in master data and placed. A random showcase is controlled by the following parameters. Item Description maximumNumberOfChoice The maximum number of DisplayItems placed in a single drawing displayItems The list of RandomDisplayItems eligible for drawing. Each item has a weight (drawing weight) and stock (inventory). baseTimestamp / resetIntervalHours The interval at which the displayed contents are redrawn. The display is refreshed at a fixed interval starting from the specified time. salesPeriodEventId A GS2-Schedule event ID. Specify this when you want to restrict the sales period. The drawing result is stored per player as RandomShowcaseStatus , and stock is consumed at the time of purchase. When the redraw interval is reached, the displayed contents are updated on the next access. Adjustment via Buffs By integrating with GS2-Buff, you can dynamically adjust acquireActions , verifyActions , and consumeActions of DisplayItem and RandomDisplayItemModel. For random display items, the stock can also be overwritten. This allows flexible modification of rewards, required costs, and inventory quantities to align with events or campaigns. Script Triggers By setting buyScript on the namespace, you can invoke a custom script at the timing of an item purchase. The main configurable event triggers and script setting names are as follows: buyScript : When an item is purchased By leveraging these, you can insert custom validation, audit log output, KPI aggregation, etc., into the purchase process. Transaction Actions GS2-Showcase provides the following transaction actions: Consume actions: increment purchase count Acquire actions: decrement purchase count, force re-draw of a random showcase By using “force re-draw of a random showcase” as an acquire action, you can safely execute processes such as forcefully updating the shop’s displayed items as a reward when a specific item is obtained or a quest is cleared, all within a transaction. This enables providing a product lineup that is timely and aligned with the player’s progress. Additionally, by using “decrement purchase count,” operations such as individually restoring product purchase limits (for example, re-releasing limited items) are also facilitated. Master Data Operation Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: ShowcaseModel : Definition of a standard showcase. You can place SalesItem or SalesItemGroup as DisplayItem . RandomShowcaseModel : Definition of a random showcase. maximumNumberOfChoice items are drawn from a list of RandomDisplayItemModel and displayed. SalesItem / SalesItemMaster : Definition of a single product for sale. SalesItemGroup / SalesItemGroupMaster : Definition of a product group whose displayed contents change depending on the purchase status. Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. The following is a JSON example of master data including a random showcase. { \"version\": \"2019-09-13\", \"showcases\": [ { \"name\": \"showcase-0001\", \"metadata\": \"Regular shop\", \"salesPeriodEventId\": null, \"displayItems\": [ { \"displayItemId\": \"display-item-0001\", \"type\": \"salesItem\", \"salesItemName\": \"item-0001\" } ] } ], \"randomShowcases\": [ { \"name\": \"random-showcase-0001\", \"metadata\": \"Daily shop\", \"maximumNumberOfChoice\": 4, \"baseTimestamp\": 1700000000000, \"resetIntervalHours\": 24, \"displayItems\": [ { \"name\": \"display-item-0001\", \"weight\": 10, \"stock\": 3, \"consumeActions\": [], \"acquireActions\": [] } ] } ] } Example Implementation Standard Showcase Get a showcase Get a list of showcases An API for retrieving the list of showcases is not provided in the game engine SDK. If you need to retrieve it, please use the Management Console / GS2 CLI / general SDKs for each language (C# / Go / Python / TypeScript / PHP / Java). Buy an item Buy is executed as a transaction processed through GS2-Distributor. To reflect the transaction result, call WaitAsync / Wait on the returned EzTransactionDomain and wait for the transaction to complete. Random Showcase Get a showcase Buy an item Get the state of a random showcase A random showcase holds, per player, the drawing result and purchase count as RandomShowcaseStatus . Retrieve this when you want to check the next redraw time or the number of items already purchased. Detailed Reference GS2-Showcase Reference","lang":"en","section":"microservices","summary":"Product sales feature","title":"GS2-Showcase","url":"/microservices/showcase/"},{"content":"This microservice realizes the skill tree functionality commonly used as a growth element for characters and other objects. A skill tree is a feature with a tree structure such as the one shown below, in which releasing nodes improves a character’s parameters. Releasing a node requires a cost, and GS2-SkillTree allows you to set the consume actions provided by each microservice. flowchart TD Base --\u003e Node1[STR+5] Node1 --\u003e Node2[DEF+5] Node2 --\u003e Node3[SPD+5] Node3 --\u003e Node4[STR+5] Node4 --\u003e Node5[DEF+5] Node5 --\u003e Node6[STR+5] Node6 --\u003e Node7[DEF+5] Node3 --\u003e Node10[SPD+5] Node10 --\u003e Node11[DEF+5] Node11 --\u003e Node12[SPD+5] Node12 --\u003e Node13[DEF+5] Node11 --\u003e Node30[SPD+5] Node30 --\u003e Node31[STR+5] Node31 --\u003e Node32[SPD+5] Node7 --\u003e Node20[STR+5] Node13 --\u003e Node20 Node20 --\u003e Node21[STR+5] Node21 --\u003e Node22[STR+5] Node Definition (NodeModel) Nodes that make up the skill tree are defined as the master data NodeModel . Each node consists of the following fields, which express the release conditions, cost, effect, and dependencies of the node. Field Role name Identifier of the node metadata Descriptive text displayed on the client releaseVerifyActions Verify actions required for release (e.g., being at a specific rank; up to 10) releaseConsumeActions Actions consumed at release (SP, items, gold, etc.; 1 to 10) restrainReturnRate Cost return rate when un-releasing (restraining) (0.0 to 1.0, default 1.0) premiseNodeNames Prerequisite nodes (up to 10) The acquire actions returned when un-released ( returnAcquireActions ) are automatically generated by inverting releaseConsumeActions and multiplying by restrainReturnRate . Skill effects (such as stat increases) should be expressed by linking the resources consumed in releaseConsumeActions (such as GS2-Experience rank or GS2-Inventory skill points) with another microservice. Prerequisite Nodes Each node can have prerequisite nodes configured to form a tree structure. Up to 10 nodes can be set as prerequisite nodes, and a node cannot be released unless the nodes set as prerequisites are in the released state. Note that you do not have to set all nodes leading up to that node as prerequisites; you only need to specify the one immediately preceding it to form the tree structure. flowchart LR A --\u003e B B --\u003e C C --\u003e D In the example above, it is sufficient to specify only C for D’s premiseNodeNames . A and B are necessarily already released in order to release C, so they do not need to be described as dependencies. Release Process Flow sequenceDiagram participant Client participant SkillTree as GS2-SkillTree participant Other as Other microservices Client-\u003e\u003eSkillTree: Release(nodeModelNames) SkillTree-\u003e\u003eSkillTree: Check prerequisite nodes SkillTree-\u003e\u003eSkillTree: Verify releaseVerifyActions SkillTree-\u003e\u003eOther: Execute releaseConsumeActions SkillTree--\u003e\u003eClient: List of released nodes (Status) Reverting released nodes to unreleased You can revert each node, or all nodes, to the unreleased state. This can be used to implement a “respec” feature in which the player rebuilds their build. Cost reimbursement In this case, the cost consumed to release the node can be returned based on the rate specified in restrainReturnRate . It is important to note here that transaction consume actions come in two kinds: “reversible” and “non-reversible.” “Reversible” consume actions are refunded, while “non-reversible” consume actions are not. Please refer to the documentation for each microservice to check whether its consume actions are reversible. Manipulating nodes in the middle of the tree If a node that depends on this node has already been released, the node cannot be reverted to the unreleased state. For example, with a dependency chain A → B → C, you cannot un-release B while C remains released. To implement a respec, either un-release nodes in order from the leaves of the dependency, or use ResetAsync (described later) to revert all nodes at once. Batch release of nodes Multiple nodes can be released at once. You do not need to specify nodes in dependency order; GS2-SkillTree resolves the dependency order and processes the release while determining whether each release is possible. Script Triggers Setting releaseScript and restrainScript on the namespace allows you to invoke a custom script at the timing of node release or reverting a node to unreleased. The main configurable event triggers and script setting names are as follows: releaseScript : When a node is released restrainScript : When a node is reverted to unreleased Master Data Operation Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: NodeModel : Skill tree node definition JSON example of master data { \"version\": \"2024-05-30\", \"nodeModels\": [ { \"name\": \"str-001\", \"metadata\": \"STR+5\", \"premiseNodeNames\": [], \"releaseConsumeActions\": [ { \"action\": \"Gs2Inventory:ConsumeItemSetByUserId\", \"request\": \"{\\\"namespaceName\\\":\\\"inventory-0001\\\",\\\"inventoryName\\\":\\\"skill_point\\\",\\\"itemName\\\":\\\"sp\\\",\\\"userId\\\":\\\"#{userId}\\\",\\\"consumeCount\\\":1}\" } ], \"restrainReturnRate\": 1.0 }, { \"name\": \"str-002\", \"metadata\": \"STR+10\", \"premiseNodeNames\": [\"str-001\"], \"releaseConsumeActions\": [ { \"action\": \"Gs2Inventory:ConsumeItemSetByUserId\", \"request\": \"{\\\"namespaceName\\\":\\\"inventory-0001\\\",\\\"inventoryName\\\":\\\"skill_point\\\",\\\"itemName\\\":\\\"sp\\\",\\\"userId\\\":\\\"#{userId}\\\",\\\"consumeCount\\\":2}\" } ], \"restrainReturnRate\": 1.0 } ] } Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Adjustment via Buffs Using GS2-Buff, you can adjust the releaseVerifyActions , releaseConsumeActions , and restrainReturnRate of a node model via buffs, dynamically adjusting release conditions, costs, and return rates according to events. For example, you can implement measures such as “release is possible with just 1 skill point” or “return rate is 1.5x when respeccing” as a limited-time event, without rewriting the master data, simply by applying buffs. Transaction Actions GS2-SkillTree provides the following transaction actions: Consume actions: mark a node as unreleased Acquire actions: record a node as released By using “record a node as released” as an acquire action, you can safely execute processes within a transaction to directly mark specific nodes in the skill tree as released as a reward for purchasing an item at a shop or clearing a quest. This enables flexible character growth, such as immediately granting special skills to players who achieve specific conditions without consuming costs. Example Implementation Get the release status of nodes Status contains the list of currently released nodes ( releasedNodeNames ). If you want to manage separate skill trees per character, you can hold multiple skill tree states by specifying propertyId . Release a node Multiple nodes can be passed in at once. Even if you specify them including prerequisite relationships, GS2-SkillTree resolves the order and attempts to release them. Revert the release state of a node Reverts the specified nodes to the unreleased state. Consumed actions are returned based on the rate specified in restrainReturnRate (only for reversible consume actions). Reset the release state of nodes Reverts all released nodes to unreleased at once. This can be used for specifications such as consuming a “skill respec item.” For all nodes, cost return is attempted in accordance with restrainReturnRate . Managing skill trees per character In cases where a single account has multiple characters that each have an independent skill tree, you can leverage the propertyId of Status . By assigning the character ID managed in GS2-Dictionary or GS2-Inventory directly as the propertyId , you can save an independent release state per character. Detailed Reference GS2-SkillTree Reference","lang":"en","section":"microservices","summary":"Skill tree feature","title":"GS2-SkillTree","url":"/microservices/skill_tree/"},{"content":"Stamina is a feature that realizes in-game limits on the number of times something can be done. GS2-Limit expresses limits like “3 times a day,” but GS2-Stamina expresses limits with a combination of time progression and consume actions, such as “use stamina that recovers 1 point every 8 hours to enforce a limit of 3 times per day.” In the case of stamina, by varying the points consumed, you can realize specifications such as “action A is 3 times per day, action B is 5 times per day.” By providing guidelines for experience or in-game currency obtained per stamina point, you can eliminate “efficient” actions in the game and make it easier to adjust the game balance, since no single action becomes optimal regardless of what is chosen. Developers should strive to have players log in every day, so this kind of specification is not often used, but for players, a specification in which 1 point recovers every 8 hours and accumulates up to 15 points means they can use up all their points without waste by logging in only once every 5 days. Stamina Stamina is configured with “recovery interval,” “recovery amount,” and “maximum value.” graph LR Time[\"Time progression\"] -- \"every recoverIntervalMinutes\" --\u003e Recover[\"Recover (+recoverValue)\"] Recover --\u003e Value[\"Current value\"] Consume[\"Consume action\"] -- \"-consumeValue\" --\u003e Value Value -- \"exceeds maxValue\" --\u003e Overflow[\"Overflow state\"] Parameter Description value Current stamina value held maxValue The upper limit reachable by natural recovery recoverIntervalMinutes Minutes required to recover 1 point recoverValue Value increased per recovery overflowValue Amount exceeding the maximum value nextRecoverAt Scheduled date/time of the next recovery Overflow Stamina can be recovered beyond the maximum value. If the maximum is exceeded, no recovery over time occurs. Also, even when the maximum is exceeded, you can set a “true maximum” beyond which no further addition is allowed (for UI reasons, etc.). Why allow overflow? This specification may seem strange to developers who have not had the opportunity to play games that incorporate stamina. Generally, stamina has items or in-game purchases that recover it. This specification was created to minimize the stress on the player when using such items or purchasing stamina. Here is a concrete example. In this game, 1 point of stamina recovers every 5 minutes, and your maximum stamina is 50 points. You need 10 stamina points to play the next quest you want to play. However, your current stamina is only 9 points, and you must wait 5 minutes before you can play the next quest. So you decide to purchase stamina. Purchasing stamina recovers 50 stamina points. However, if you purchase stamina right now, even though 50 points recover, 9 points will be wasted. So you wait 5 minutes for 1 point to recover, play the quest to bring stamina to 0, and then purchase stamina to play the next quest. This does not allow players to play the game comfortably. That is why games appeared that introduced a specification allowing stamina to be recovered beyond the maximum value. Let’s see how the user experience changes when the overflow specification is added to stamina. Currently your stamina is only 9 points, and you must wait 5 minutes before you can play the next quest. So you purchase stamina, recover 50 stamina points, and now have 59 points. In this state, recovery of stamina over time no longer occurs, but you immediately start the next quest, bringing stamina to 49 points. Integration with GS2-Experience By registering MaxStaminaTable / RecoverIntervalTable / RecoverValueTable as master data, you can automatically change the maximum value, recovery interval, and recovery amount based on the GS2-Experience rank (player level, etc.). You can easily express the common growth element of automatically increasing the stamina cap as the player levels up. Synchronizing natural recovery Calling the Apply API can immediately reflect natural stamina recovery for the time elapsed since the last access. Normally, this is automatically reflected inside the stamina retrieval API, so there is little need to call it explicitly. Use it when you need to strictly synchronize the stamina value on the server side. Script Triggers Setting overflowTriggerScript on the namespace allows you to execute a custom script when stamina exceeds the maximum value via natural recovery. This enables applications such as converting overflowed stamina into another resource at overflow time. The main configurable event triggers and script setting names are as follows: overflowTriggerScript : When stamina overflows Adjustment via Buffs By integrating with GS2-Buff, you can use buffs to adjust maxValue , recoverIntervalMinutes , recoverValue , as well as action parameters such as consumeValue and recoverValue , allowing flexible adjustment of the stamina cap, recovery speed, and consumption amount for events and similar purposes. This can be used for time-limited gameplay adjustments such as “make the stamina cap 1.5x for a limited time” or “double the recovery speed for one hour right after login.” Transaction Actions GS2-Stamina provides the following transaction actions: Verify actions: verify the current value, verify the maximum value, verify the recovery speed, verify the recovery amount, verify the overflow amount Consume actions: consume stamina, decrement the maximum value Acquire actions: recover (add) stamina, increment/set the maximum value, set the recovery speed, set the recovery amount By using “increment maximum value” as an acquire action, you can safely execute processes within a transaction to automatically expand the maximum stamina capacity, such as when an item is purchased at a shop or when the player’s rank increases. This makes it easier to design rewards that make players feel their growth. Additionally, by setting “recover stamina” as a reward, you can fully restore stamina upon completion of a specific mission to encourage continued play. Master Data Operation Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: StaminaModel : Definition of recovery amount, recovery interval, maximum value, and whether overflow is allowed MaxStaminaTable : A table that derives the maximum value from a GS2-Experience rank RecoverIntervalTable : A table that derives the recovery interval from a GS2-Experience rank RecoverValueTable : A table that derives the recovery amount from a GS2-Experience rank The following is a JSON example of master data. { \"version\": \"2019-04-23\", \"staminaModels\": [ { \"name\": \"stamina-0001\", \"metadata\": \"Stamina for quests\", \"recoverIntervalMinutes\": 5, \"recoverValue\": 1, \"initialCapacity\": 50, \"isOverflow\": true, \"maxCapacity\": 999 } ] } Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Example Implementation Get the current stamina value The stamina value returned reflects natural recovery up to the moment of retrieval. Get a list of stamina Among multiple StaminaModel s registered in the namespace, you can retrieve the current value of all stamina the player is using in a single call. Consume stamina It is not recommended to consume stamina directly via this API. By consuming stamina through a service such as GS2-Quest, you can safely handle the consumption together with processing such as starting a quest or obtaining items as a single transaction. Apply natural recovery Immediately reflects natural recovery for the time elapsed since the last access. Normally this is reflected automatically inside API calls, so there is little need to call it explicitly. Applied example: gathering feature in a city-building game By applying the stamina mechanism, you can also implement a gathering feature in a city-building game. By setting up buildings in the stamina model and expressing the stamina value as the production output of the buildings, you can realize a gathering system in which resources accumulate over time. For example, you can treat “an iron ore mine that produces iron ore” as a single stamina model, where the recovery interval represents the mining interval, the recovery amount the amount mined per cycle, and the maximum value the warehouse cap. When the player performs a collection action, the entire amount is consumed with Consume , and the resulting point count is stored as items in GS2-Inventory. Detailed Reference GS2-Stamina Reference","lang":"en","section":"microservices","summary":"Stamina feature\n","title":"GS2-Stamina","url":"/microservices/stamina/"},{"content":"GS2-Quest provided a mechanism to manage the start and end of quests and to receive rewards on completion according to the quest started. However, GS2-Quest had a problem handling game specifications where in-game randomness is strong and rewards are difficult to determine in advance. GS2-StateMachine was developed to manage in-game state at a finer granularity. State Machine The state machine is what is used to manage in-game state. flowchart TD Start ----\u003e MainStateMachine_Initialize MainStateMachine_Pass ----\u003e Exit subgraph MainStateMachine MainStateMachine_Initialize[[Initialize]] --\u003e|Pass| MainStateMachine_ChoiceSkill MainStateMachine_ChoiceSkill[/ChoiceSkill/] MainStateMachine_InGame([InGame]) --\u003e|Pass| MainStateMachine_NextTurn MainStateMachine_InGame([InGame]) --\u003e|Fail| MainStateMachine_Pass MainStateMachine_NextTurn[[NextTurn]] --\u003e|Next| MainStateMachine_ChoiceSkill MainStateMachine_NextTurn[[NextTurn]] --\u003e|Exit| MainStateMachine_Pass MainStateMachine_Pass[\\Pass/] subgraph ChoiceSkill ChoiceSkill_Initialize[[Initialize]] --\u003e|Pass| ChoiceSkill_LotterySkills ChoiceSkill_LotterySkills[[LotterySkills]] --\u003e|Pass| ChoiceSkill_WaitChoiceSkill ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) --\u003e|ChoiceSkill| ChoiceSkill_ChoiceSkill ChoiceSkill_WaitChoiceSkill([WaitChoiceSkill]) --\u003e|ReLotterySkill| ChoiceSkill_ReLotterySkill ChoiceSkill_ReLotterySkill[[ReLotterySkill]] --\u003e|Pass| ChoiceSkill_LotterySkills ChoiceSkill_ReLotterySkill[[ReLotterySkill]] --\u003e|AlreadyReLottery| ChoiceSkill_WaitChoiceSkill ChoiceSkill_ChoiceSkill[[ChoiceSkill]] --\u003e|Pass| ChoiceSkill_Pass ChoiceSkill_ChoiceSkill[[ChoiceSkill]] --\u003e|InvalidSkillIndex| ChoiceSkill_WaitChoiceSkill ChoiceSkill_Pass[\\Pass/] end end MainStateMachine_ChoiceSkill --\u003e ChoiceSkill_Initialize ChoiceSkill_Pass --\u003e|Pass| MainStateMachine_InGame Player -----\u003e|Interaction| MainStateMachine_InGame Player -----\u003e|Interaction| ChoiceSkill_WaitChoiceSkill If you are a programmer, you have probably received a flowchart like the one above from your planner. Such a representation of state transitions is a state machine. It manages which state the player is currently in and the values of the variables usable inside the state machine. The state machine will eventually transition to an end state, and rewards can be determined by the state variables the state machine holds at that time. Events and Transitions What connects the states of a state machine are transitions. A transition sets the conditions under which one state transitions to the next state. The condition can be the receipt of an event, and the next state to transition to can vary by event type. Events can be emitted from scripts running inside the state machine, but can also be accepted from the player. This allows processing to branch according to the choices the player made or the game result. Events can carry parameters, so even without preparing one event per choice, you can keep the state machine simple by passing an event meaning “selected from the choices” together with a parameter representing “what was selected.” State Machine Version Management State machines are versioned, and even if you update the state machine contents, those started before continue to operate with the state machine definition that was in use at startup time. This allows you to apply a new state machine definition without affecting running state machines. If you make a change that breaks compatibility, please use the namespace setting mechanism that treats state machines started with a version below the specified version as deleted. Note that only the state machine definition is versioned. The GS2-Script referenced by the state machine is not versioned, so caution is required. A started state machine can have an expiration set in minutes; when the expiration is reached, it is automatically deleted. State Machine Definition Language The state machine is defined using GS2 States Language (GSL), which was developed by GS2. GSL is written using the following notation. StateMachine MainStateMachine { Variables { int turn; int choiceSkill; array skills; } EntryPoint Initialize; Task Initialize() { Event Pass(); Event Error(string reason); Script grn:gs2:{region}:{ownerId}:script:statemachine-script:script:MainStateMachine_Initialize } SubStateMachineTask ChoiceSkill { using ChoiceSkill; in (turn choiceSkill); } WaitTask InGame { Event Pass(); Event Fail(); Event Error(string reason); } Task NextTurn() { Event Next(); Event Exit(); Event Error(string reason); Script grn:gs2:{region}:{ownerId}:script:statemachine-script:script:MainStateMachine_NextTurn } PassTask Pass; ErrorTask Error(string reason); Transition Initialize handling Pass -\u003e ChoiceSkill; Transition Initialize handling Error -\u003e Error; Transition ChoiceSkill handling Pass -\u003e InGame; Transition InGame handling Pass -\u003e NextTurn; Transition InGame handling Fail -\u003e Pass; Transition InGame handling Error -\u003e Error; Transition NextTurn handling Next -\u003e ChoiceSkill; Transition NextTurn handling Exit -\u003e Pass; Transition NextTurn handling Error -\u003e Error; } For detailed specifications, please refer to About the GS2 States Language specification . Speculative Execution of State Machines The state machine provided by GS2-StateMachine can use speculative execution in Unity. This feature allows server programs with complex logic to be realized without making players feel communication time, while still preventing cheating. State Machine Speculative Execution Mechanism actor Player participant \"Game\" participant \"GS2-SDK\" participant \"Local State Machine\" participant \"Event Stream\" participant \"GS2-StateMachine\" Player -\u003e \"Game\" : Play \"Game\" -\u003e \"GS2-SDK\" : Load State Machine \"GS2-SDK\" -\u003e \"GS2-StateMachine\" : Load State Machine \"GS2-SDK\" \"Local State Machine\" : Start Local State Machine \"Local State Machine\" -\u003e \"Event Stream\" : Create Stream \"GS2-SDK\" \"Game\" : Control \"Game\" -\u003e \"Local State Machine\" : Emit Message \"Local State Machine\" -\u003e \"Event Stream\" : Write Emit Event \"Local State Machine\" -\u003e \"Local State Machine\" : Change State \"Local State Machine\" -\u003e \"Event Stream\" : Write State Variables Hash \"Game\" \"GS2-StateMachine\" : Report Events note over \"GS2-StateMachine\" : The server replays the events\\nto verify that the state variable hash values match group Hash Mismatch \"GS2-SDK\" \"GS2-SDK\" : Load State Machine \"GS2-SDK\" -\u003e \"GS2-StateMachine\" : Load State Machine \"GS2-SDK\" \"Local State Machine\" : Restart Local State Machine (state rolls back for up to 3 seconds) end end end As shown in the figure, the local state machine has the ability to execute GSL received from the server. However, it does not have the authority to rewrite user data on the server, and user data rewrites that occur inside the state machine only rewrite the SDK’s local cache. The local state machine performs state transitions based on messages received from the game, while recording the hash values of received messages and the state machine’s state variables in the event stream. The event stream sends a report to GS2-StateMachine every 3 seconds if any events have occurred. When GS2-StateMachine receives the report, it executes the events recorded in it against the state machine maintained on the server. When state transitions occur, it verifies that they match the hash values of state variables included in the report; if there are no problems up to the last event, it actually executes the user data rewrites performed by the state machine and saves the state of the state machine in the database. If the destination state differs or there is a mismatch in state variable hash values, a “state mismatch” error is returned. This can be handled from the game program via the local state machine’s OnDetectStateMismatch callback. Once a mismatch occurs, the event stream stops reporting to GS2-StateMachine, so the local state machine must be re-created. At this time, a rollback may occur up to the last state in which consistency was confirmed (the state saved to the database). Random numbers in state machines There will be times when a state machine wants to branch processing based on random numbers. For such purposes, a random number generator that shares a random number seed with the server can be used. category = 1 result = util.shared_random(category) if result.isError then fail(result['statusCode'], result['errorMessage']) end random_value = result[\"result\"] By specifying different values for category per use, you can obtain random numbers based on different random number sequences. By leveraging this mechanism, you can achieve a high level of resistance against cherry-picking of random number values. Random numbers generated by this method are guaranteed to yield exactly the same values on the server, and state mismatches based on random numbers do not occur. Transaction processing in state machines When rewriting user data during the execution of the state machine, do not use GS2-SDK for Lua; use the dedicated syntax instead. By doing so, even during speculative execution, the SDK can rewrite its cached data without communication, allowing user data rewrites to also benefit from speculative execution. For details on the API, please refer to the transaction action documentation of each microservice. transaction.execute({ consumeActions={}, acquireActions={ transaction.service(\"inventory\").acquire.acquire_simple_items_by_user_id({ namespaceName=\"namespace\", inventoryName=\"inventory\", acquireCounts={ { itemName=\"item\", count=1, }, }, }) } }) Communication processing in state machines In a state machine that uses speculative execution, it is not recommended to communicate with the outside world. The reason is that if external factors cause differences in the result of state machine execution, the likelihood of state mismatch increases dramatically. Local state machine runtime environment To be able to use a local state machine, you must install LocalStateMachineKit separately from GS2-SDK. LocalStateMachineKit can be installed from the GS2-SDK Installer. However, since this introduces additional open source libraries, you should pay attention to license notices. For details, see GS2 LocalStateMachineKit for Unity . Script Integration When a Task state is executed inside the state machine, GS2-Script can be invoked. By returning an “event” as the result of the script execution, you can transition the state machine based on the script’s logic. Master Data Management Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: StateMachineMaster : State machine definition (GSL). It is versioned; if you want to make a breaking change, you can use lowestStateMachineVersion in the namespace settings to treat state machines started with an older version as deleted. Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Script Triggers You can invoke GS2-Script when a state machine starts or when it reaches an end state. The main configurable event triggers and script setting names are as follows: startScript : When the state machine starts passScript : When the state machine reaches a PassTask errorScript : When the state machine reaches an ErrorTask Note that GS2-Script invoked from a Task state inside the state machine is specified separately via the Script directive in GSL and is used to drive state transitions themselves. Transaction Actions GS2-StateMachine provides the following transaction actions: Acquire actions: start a state machine By using “start a state machine” as an acquire action, you can safely execute, within a transaction, processing that directly starts a specific in-game session (such as a game loop involving complex state management, like roguelike dungeon exploration) as a reward when an item is purchased at a shop or a mission is achieved. This enables a smooth experience that connects purchase to play start. For rewriting user data from within the state machine, you can issue transaction actions consistent with the speculative execution of the local state machine using the transaction.execute syntax. See Transaction processing in state machines for details. Example Implementation Starting the state machine Starting a state machine cannot be processed by the game engine SDK. Please configure it as a reward in a microservice such as GS2-Quest. Send an event to the state machine Get state machine state Local state machine (speculative execution of state machine) Start a local state machine Send an event to the local state machine Handling state mismatch When you receive a state mismatch callback, re-fetch the latest state machine state from the server and restart from the local state machine startup. Dispatching the event stream While using the local state machine, you must call the Dispatch function at a regular interval so that the event stream sends events to GS2-StateMachine. Detailed Reference GS2-StateMachine Reference","lang":"en","section":"microservices","summary":"State machine management feature","title":"GS2-StateMachine","url":"/microservices/state_machine/"},{"content":"Provides the ability to determine the version of the application, the version of any additional assets, and the version of the terms of service the player has agreed to. If the version check passes, a new temporary GS2 client ID/secret can be issued. By using this feature, the GS2 client ID/secret embedded in the application only has the authority to call the APIs that perform login and version check, and only after passing the version check can it receive a client ID/secret with the privileges sufficient to actually play the game. graph TD Boot[\"App startup\"] --\u003e Login[\"Log in with GS2-Account\"] Login -- \"minimum-privilege client ID/secret\" --\u003e Check[\"GS2-Version CheckVersion\"] Check -- \"OK\" --\u003e Token[\"Obtain a new ProjectToken (intended privileges)\"] Check -- \"Warning\" --\u003e Notify[\"Prompt the player to update\"] Check -- \"Error\" --\u003e Force[\"Force version up\"] Notify --\u003e Token Token --\u003e Game[\"Main game\"] Version Model Up to 10 version models can be declared in a namespace. Multiple items can be configured for a version check, and the check is passed only when all the version checks pass. There are two kinds of version models: “perform the version check based on the version sent by the application,” and “perform the version check based on the version of the agreement that the logged-in user has agreed to in the past.\" The former is called “passive version check” and the latter is called “active version check.” Master item Description name Version model name (identifier at check time) scope passive (passive) / active (active) type simple (single threshold) / schedule (switch threshold by time) currentVersion The version automatically considered approved on first participation in an active version check warningVersion Version threshold that triggers a warning (returns warnings at or below this version) errorVersion Version threshold that triggers an error (returns errors at or below this version) scheduleVersions Defines per-time thresholds when type: schedule needSignature Whether a signature is required on version information signatureKeyId Key ID of GS2-Key used for signature verification approveRequirement Approval requirement for active version checks ( required / optional ) Version number format {major}.{minor}.{micro} format version numbers can be used, and each element can be specified as an integer value. Version values are compared in the order major → minor → micro , and they are compared as numbers, not lexicographically. Passive Version Check Used to check the version of the game’s executable binaries and each asset downloaded by the game. In the master data, you can set a “version threshold for warnings” and a “version threshold for errors” for each version model. The client sends the current app build number and downloaded asset versions to the CheckVersion API, and receives the threshold-determined result from the server. The result is one of the following: Result Condition Expected behavior Passed All items exceed warningVersion Proceed to the main game Warning ( warnings ) Any is at or below warningVersion , and above errorVersion Prompt the player to update, but allow proceeding Error ( errors ) Any is at or below errorVersion Force version up Active Version Check Used for cases such as the EULA, privacy policy, or terms revisions in specific regions, to determine “which version the player has agreed to.” By calling the AcceptVersion API, the user can put an arbitrary version into the approved state. The threshold determination targets the approval version recorded on the server, not the version sent from the client, so impersonation cannot be used to bypass terms agreement. Threshold switching by schedule When you choose type: schedule , you can configure GS2-Schedule event IDs and the version during their event period in scheduleVersions . For example, you can reserve operations like “starting December 1, terms of service v2 is required” without a deploy. Signature verification By enabling needSignature , you can require signed version information at CheckVersion . Since the signature is verified with a key issued by GS2-Key ( signatureKeyId ), tampered version information can be rejected. Script Triggers By setting checkVersionTriggerScriptId and acceptVersionScript on the namespace, you can execute custom scripts at the time of a version check or version approval. The main configurable event triggers and script setting names are as follows: checkVersionTriggerScriptId : Script invoked during version check processing. You can add dynamic determination logic. acceptVersionScript : Script invoked when a version is approved. Transaction Actions GS2-Version provides the following transaction actions: Acquire actions Action Purpose Gs2Version:AcceptByUserId Puts the specified version into the approved state (for active version checks). By using “approve a specified version” as an acquire action, you can perform processing such as automatically marking specific terms or versions as approved when a particular item is obtained or a mission is achieved. Master Data Operation Registering master data allows you to configure data and behaviors available to the microservice. Master data types include the following: VersionModel : Version model definition The following is a JSON example of master data. { \"version\": \"2019-08-19\", \"versionModels\": [ { \"name\": \"app\", \"metadata\": \"Application body\", \"scope\": \"passive\", \"type\": \"simple\", \"warningVersion\": { \"major\": 1, \"minor\": 2, \"micro\": 0 }, \"errorVersion\": { \"major\": 1, \"minor\": 0, \"micro\": 0 } }, { \"name\": \"eula\", \"metadata\": \"Terms of service\", \"scope\": \"active\", \"type\": \"simple\", \"currentVersion\": { \"major\": 1, \"minor\": 0, \"micro\": 0 }, \"warningVersion\": { \"major\": 1, \"minor\": 0, \"micro\": 0 }, \"errorVersion\": { \"major\": 1, \"minor\": 0, \"micro\": 0 }, \"approveRequirement\": \"required\" } ] } Master data can be registered via the Management Console, by reflecting data from GitHub, or by setting up workflows to register via CI using GS2-Deploy. Example Implementation Execute a version check The result of CheckVersion includes the items that match warnings ( Warnings ), the items that match errors ( Errors ), and the ProjectToken issued on success. When you receive a ProjectToken , by re-authenticating with it you can obtain a session with the privileges actually required to play the game. Agree to an active version check Call AcceptAsync when the user presses the agree button on the terms of service, for example. The agreed version is recorded per user in the AcceptVersion model and is referenced by subsequent calls to CheckVersion . Get the version model You can fetch the version model itself to display the “current terms version” and “warning threshold” in the UI. More practical information Version update operating procedures When updating a version, you may want to kick out all players currently playing so they can only play with the latest version. GS2-Version can stop new logins, but for already-logged-in players it is possible to continue access until the expiration of the client ID/client secret temporarily issued after the version check. Therefore, disconnect the always-on notification session provided by GS2-Gateway for all players, and have the game handle the session disconnection and perform a reconnection process after the version check. If the version check fails, the game enters the version-up sequence directly. This allows you to update the version and force a version check on all players in play as well. Leveraging temporary client IDs By combining with ProjectToken , you can adopt a two-stage authentication configuration in which the client ID/secret embedded in the app at startup is granted only the minimum privileges (sufficient only for login and version check), and the powerful privileges required for actual gameplay are exercised via the ProjectToken obtained after passing the version check. With this, even if the client ID/secret is leaked via reverse engineering of the app, the damage can be limited to bypassing the version check. Detailed Reference GS2-Version Reference","lang":"en","section":"microservices","summary":"Version check feature\n","title":"GS2-Version","url":"/microservices/version/"},{"content":"Introduction GS2 States Language (GSL) is a state machine definition language with a unique structure. A state machine is generally composed of Tasks, which represent multiple states, and Transitions, which represent transitions between tasks. When a message is sent from the outside, the “running Task” transitions based on the rules defined by the Transition to manage the state. In addition to “running Tasks,” a state machine also has “state variables. There are several different types of Tasks, but in general, the process can be described by executing a GS2-Script. GS2-Script can refer to “state variables” and can rewrite “state variables” as a result of script execution. (C) Game Server Services Inc. and affiliates. Implementation of GSL specifications and derivative specifications are permitted free of charge. However, the above copyright notice must be included in any derivative works. You may not sublicense or sell derivative works of this specification. This specification is provided “as is” without warranty of any kind, either express or implied, including, but not limited to, the implied warranties that this specification does not infringe the copyrights of others. Game Server Services, Inc. shall not be liable for any claims, damages, or other liability arising out of this use. The sample code contained in this specification is licensed under the Apache License, Version 2.0 unless otherwise indicated. GSL Examples StateMachine MainStateMachine { Variables { int counter; } EntryPoint Task1; Task Task1(int initCounter) { Event StartLoop(); Event Error(string Reason); Payload { args.variables.counter = args.params.initCounter result = { event=\"StartLoop\", params={}, updatedVariables=args.variables } } } SubStateMachineTask Task2 { using SubStateMachine; in (initCounter counter); } WaitTask WaitForExternalEvent { Event ExternalEvent(int newCounter); } Task Task3(int newCounter) { Event Pass(); Payload { print(args.variables.counter) print(args.params.newCounter) result = { event=\"Pass\", params={}, updatedVariables=args.variables } } } PassTask Pass; ErrorTask Error(string reason); Transition Task1 handling StartLoop -\u003e Task2; Transition Task2 handling Pass -\u003e WaitForExternalEvent; Transition Task2 handling Error -\u003e Error; Transition WaitForExternalEvent handling ExternalEvent -\u003e Task3; Transition Task3 handling Pass -\u003e Pass; } StateMachine SubStateMachine { Variables { int currentCounter; int loopCounter; } EntryPoint SubTask1; Task SubTask1(int initCounter) { Event Pass(); Event Error(string reason); Script grn:gs2:{region}:{ownerId}:script:state-machine-0001:script:SubTask1 } Task SubTask2(int currentCounter) { Event IncrementCounter(); Event Pass(); Event Error(string reason); Script grn:gs2:{region}:{ownerId}:script:state-machine-0001:script:SubTask2 } PassTask Pass; ErrorTask Error(string reason); Transition SubTask1 handling Pass -\u003e SubTask2; Transition SubTask1 handling Error -\u003e Error; Transition SubTask2 handling IncrementCounter -\u003e SubTask2; Transition SubTask2 handling Pass -\u003e Pass; Transition SubTask2 handling Error -\u003e Error; } GS2-Script examples corresponding to the samples SubTask1 args.variables.currentCounter = args.params.initCounter args.variables.loopCounter = 0 result = { event=\"Pass\", params={}, updatedVariables=args.variables } SubTask2 args.variables.loopCounter = args.variables.loopCounter + 1 if args.variables.currentCounter Language specification StateMachine StateMachine ${name} { } The StateMachine block is used to define a state machine, and there can be more than one in a file. A StateMachine can be named and must be unique within the file. Variables Variables { string ${variableName}; int ${variableName}; float ${variableName}; bool ${variableName}; } The Variables block allows you to specify the state variables that the state machine has. A state variable consists of a data type and a variable name. The data type can be one of the following types name | data type – | string string | String int | 64bit signed integer value float | 64bit floating point number bool | boolean value EntryPoint EntryPoint ${taskName}; EntryPoint is the first task to transition to when the state machine is invoked. Task Task defines a node that represents a state. There are several types of nodes for different purposes. Task Task ${taskName}(sting ${argumentName}, int ${argumentName}) { Event ${eventName}(); Event Error(string Reason); Script ${scriptId} } The Task block is the most common node and executes a GS2-Script script. Tasks can be named, but must be unique within the StateMachine. The name defined here is used to specify the Transition between tasks. Task ${taskName}(sting ${argumentName}, int ${argumentName}) Tasks can take arguments. Arguments may be none, singular, or multiple. Use “data type variable name” to declare arguments, and separate multiple arguments with commas. Event ${eventName}(); Event defines the type of event received during the execution of a task. An event can have a name, and you can specify additional parameters to be attached to the event. Event Error(string Reason); Note that the event Error(string Reason) must be declared. It can send a message when an error occurs in a script, but it can also be sent by internal processes, such as when a script fails to execute. Script ${scriptId} Script specifies the script GRN of the GS2-Script to execute when transitioning to a task. Payload { result = { event=\"Event\", params={}, updatedVariables=args.variables } } Payload directly specifies the GS2-Script to be executed when transitioning to the task. A Task must implement either Script or Payload. If both are described at the same time, Script is adopted. SubStateMachineTask SubStateMachineTask ${taskName} { using ${nextStateMachine}; in (${inputArgumentName} ${variableName}); } SubStateMachineTask defines the process of moving the process to another state machine. The nextStateMachine is the name of the state machine to transition to. in (${inputArgumentName} in specifies the argument to pass to the entry point of the destination state machine. inputArgumentName is the name of the argument to be received by the task at the entry point, and variableName is the value to be passed as the name of a state variable in the source state machine. out (${outputVariableName} -\u003e ${variableName}); out is the parameter that the destination state machine receives when it transitions to PassTask. outputVariableName is the name of the state variable of the destination state machine, and variableName is the name of the state variable of the current state machine that will receive the returned result. WaitTask WaitTask ${taskName} { Event ${eventName}(sting ${argumentName}, int ${argumentName}); } WaitTask is a task that does nothing in particular. It just waits for external messages to be sent. Typically used to wait for the result of a game in progress on the client. Event ${eventName}(sting ${argumentName}, int ${argumentName}); Event defines the type of event to receive while executing a task. Events can have names that are accepted to be sent out, and parameters can be added to the event. PassTask PassTask Pass; PassTask is a task that indicates the completion of a state machine on a required node. The name of the PassTask must be Pass. ErrorTask ErrorTask Error(string reason); ErrorTask is a task that indicates an abnormal termination of the state machine at a required node. The name of the ErrorTask must be Error. Transition Transition ${taskName} handling ${eventName} -\u003e ${nextTaskName}; Transition represents a transition between nodes. taskName is the name of the task to transition from, eventName is the type of event received, and nextTaskName is the name of the task to transition to.","lang":"en","section":"api_reference","summary":"Introduction GS2 States Language (GSL) is a state machine definition language with a unique structure. A state machine is generally composed of Tasks, which represent multiple states, and Transitions, which represent transitions between tasks. When a message is sent from the outside, the \u0026ldquo;running Task\u0026rdquo; transitions based on the rules defined by the Transition to manage the state.\nIn addition to \u0026ldquo;running Tasks,\u0026rdquo; a state machine also has \u0026ldquo;state variables. There are several different types of Tasks, but in general, the process can be described by executing a GS2-Script.","title":"GS2 States Language Format","url":"/api_reference/state_machine/format/"},{"content":"Implement the present box functionality. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Inbox GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Inbox/initialize_inbox_template.yaml Project Description Open the project and you will see the above. Run it and you will see a screen with nothing at the top and a menu at the bottom. Press the “Send” button three times from the menu. Three messages are displayed in the list. The top part of the screen shows the list of messages received in the gift box like this. Now press the “Send With Expire” button from the menu. A list of newly expired messages is displayed in the message list. The date and time are shown in two lines, the upper one is the received date and the lower one is the expiration date. The expiration date is set to one minute after the received date and time. Please wait for one minute. The expired message will no longer appear on its own. Next, press the “Read” button in the middle of the three messages. The Read button will be grayed out for messages you have already read. Project Description Note the hierarchy of the scene. Canvas/InboxWindow Gs2InboxNamespaceContext Specifies the namespace of the GS2-Inbox to be handled by the node under this GameObject. This time, the namespace inbox-0001 of GS2-Inbox is specified. Canvas/InboxWindow/Inbox/…/Content Gs2InboxOwnMessageListFetcher . Get a list of messages in the namespace specified by NamespaceContext. Gs2InboxOwnMessageList Generates a list of messages obtained by Gs2InboxOwnMessageListFetcher by assigning them to the specified prefab. Maximum Items specifies the maximum number of prefabs to be generated. This time, Message in the child node is specified as a prefab. If a GameObject specified as a prefab exists in the scene, that GameObject will be disabled and the number of GameObjects specified in Maximum Items will be created in addition to the GameObjects specified as prefabs. Canvas/InboxWindow/Inbox/…/Content/Message Gs2InboxOwnMessageContext Specifies the message to be handled by the node under this GameObject. The content of the context is assigned by Gs2InboxOwnMessageList. Gs2InboxOwnMessageFetcher . Gets the message specified by Gs2InboxOwnMessageContext. Canvas/InboxWindow/Inbox/…/Content/Message/Metadata Display the payload of the message. Gs2InboxOwnMessageLabel . Format the message content in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InboxWindow/Inbox/…/Content/Message/Timestamp Gs2InboxMessageExpiresAtEnabler . Controls whether to show or hide a message based on the expiration time value set in the message. If the expiration date is set, ExpiresAt is set to enable. Canvas/InboxWindow/Inbox/…/Content/Message/Timestamp/ReceivedAt Gs2InboxOwnMessageLabel The date and time the message was received are displayed. The formatting method is specified in Format, The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InboxWindow/Inbox/…/Content/Message/Timestamp/ExpiresAt Gs2InboxOwnMessageLabel Message expiration date is displayed. The formatting method is specified in Format, The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InboxWindow/Inbox/…/Content/Message/Control Gs2InboxMessageIsReadEnabler . Controls whether to show or hide the message based on the read status of the message. If the message is unread, Read is enabled; if the message is read, AlreadyRead is enabled. Canvas/InboxWindow/Inbox/…/Content/Message/Control/Gs2InboxMessageReadAction You can add a prefab from this context menu. Enabling the prefab makes the message specified in Gs2InboxOwnMessageContext readable. OnReadComplete(String) can be set to a callback when read-completion is successfully completed, and disables itself. Canvas/InboxWindow/Input/Send Gs2ExchangeRateModelContext Set the GS2-Exchange exchange rate at which GS2-Inbox messages are sent. Here, the exchange rate named SendMessage in the namespace named exchange-0002 of GS2-Exchange is specified. Canvas/ExperienceWindow/Input/Send/Gs2ExchangeExchangeAction Specify the exchange quantity in Count and activate the prefab to perform the exchange of the exchange rate specified in Gs2ExchangeRateModelContext. OnExchangeComplete(String) can be set to a callback when the exchange process is successfully completed, and disables itself. Canvas/InboxWindow/Input/Send With Expire Gs2ExchangeRateModelContext Sets the GS2-Exchange exchange rate at which GS2-Inbox expiration month messages are sent. Here, the exchange rate named SendMessageWithExpire in the namespace named exchange-0002 of GS2-Exchange is specified. Canvas/ExperienceWindow/Input/Send With Expire/Gs2ExchangeExchangeAction Specify the exchange quantity in Count and activate the prefab to perform the exchange at the exchange rate specified in Gs2ExchangeRateModelContext. OnExchangeComplete(String) can be set to a callback when the exchange process is successfully completed, and disables itself. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Inbox functionality using GS2 UIKit for Unity","title":"Sample of Inbox(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/inbox/"},{"content":"This section describes the initialization process common to all microservices. Initialization policies differ greatly between the for Game Engine and other microservices. As a general rule, the for Game Engine has more utility classes to make things easier for the developer, and the for Game Engine has more utility classes to make things easier for the developer. The difference is that initialization is performed using utility classes.","lang":"en","section":"api_reference","summary":"This section describes the initialization process common to all microservices.\nInitialization policies differ greatly between the for Game Engine and other microservices. As a general rule, the for Game Engine has more utility classes to make things easier for the developer, and the for Game Engine has more utility classes to make things easier for the developer. The difference is that initialization is performed using utility classes.","title":"Initialization process","url":"/api_reference/initialize/"},{"content":"Game Server Services provides a number of microservices to implement in-game features. The microservices described in this section will be implemented in combination according to the specifications of your game. This section focuses on what each GS2 microservice can do to help game developers plan their games. How to combine microservices GS2 microservices each have independent responsibilities, but cooperate via transaction actions. For example, the following kind of cooperation safely realizes complex game logic. graph LR Player[Player] -- Payment --\u003e Platform[AppStore/GooglePlay] Showcase[GS2-Showcase] -- Product List --\u003e Player Player -- Purchase (with Receipt) --\u003e Showcase Showcase -- Issue Transaction --\u003e Distributor[GS2-Distributor] Distributor -- Consume Action (Receipt Verification) --\u003e Money Distributor -- Acquire Action (Item Acquisition) --\u003e Inventory Each service exposes transaction actions called “verify actions”, “consume actions”, and “acquire actions”. By chaining these together via GS2-Distributor , processing that spans multiple services can be executed atomically. How to proceed with learning If this is your first time using GS2, we recommend starting by understanding GS2-Account . The concept of an anonymous account is the prerequisite for all GS2 services. Next, by reading through the pages of the feature categories your game needs in order, you can grasp how to choose services for the overall system design of your game.","lang":"en","section":"microservices","summary":"An introduction to microservices provided by Game Server Services.\n","title":"Introduction to Microservices","url":"/microservices/"},{"content":"Implement the inventory functionality. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Inventory GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Inventory/initialize_inventory_template.yaml Project Description Open the project and you will see the above. Once executed, you will see the inventory capacity usage in the upper right corner and the inventory operation buttons at the bottom. Click on “Acquire Potion.” You will then obtain 10 potions, and the potions will appear at the top of the screen. Likewise, next click on “Acquire Ether” to obtain ether. ![img_4.png]. The ether will be added next to the potion. Incidentally, the amount used in the upper right inventory is also reduced to 2/10. Next, the maximum stack of potions is set to 99, so we click “Acquire Potion” 9 more times to have 100 potions. As you can see, the potions are now separated into two stacks and the inventory usage is now 3/10. Items can be consumed by clicking on the potion or ether icons. Let’s click on a stack of 99 potions. Items can be consumed by explicitly specifying the stack, in which case there is no process of packing 98 stacked potions and 1 stacked potion. Next, let’s click on the 1 stacked potion. As you can see, the total number of stacks is now 2 and the inventory consumption is now 2/10. Project Description Note the hierarchy of the scene. Canvas/InventoryWindow Gs2InventoryOwnInventoryContext Specifies the inventory (standard) of GS2-Inventory to be handled by the node under this GameObject. This time, we specify an inventory named Bag in the namespace inventory-0001 of GS2-Inventory. Canvas/InventoryWindow/Capacity Gs2InventoryInventoryEnabler InventoryCapacityText GameObject is enabled when the inventory specified in Gs2InventoryOwnInventoryContext is finished loading. Canvas/InventoryWindow/Capacity/InventoryCapacityText Gs2InventoryInventoryLabel . Current Inventory Usage/ Current Inventory Maximum Capacity is specified in Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InventoryWindow/Inventory/…/Content Gs2InventoryOwnItemSetListFetcher Gets the list of items in the namespace specified by Gs2InventoryOwnInventoryContext. Gs2InventoryOwnItemSetList Generates the items obtained by Gs2InventoryOwnItemSetListFetcher by assigning them to the specified prefab. Maximum Items specifies the maximum number of prefabs to be generated. In this case, Item in the child node is specified as a prefab. If a GameObject specified as a prefab exists in the scene, the GameObject will be disabled and the number of GameObjects specified in Maximum Items will be created in addition to the GameObjects specified as prefabs. Canvas/InventoryWindow/Inventory/…/Content/Item Gs2InventoryOwnItemSetContext Specifies the item to be handled by the node under this GameObject. The content of the context is assigned by Gs2InventoryOwnItemSetList. Gs2InventoryItemModelFetcher Gets the item model specified by Gs2InventoryOwnItemSetContext. Gs2InventoryOwnItemSetFetcher Gets the item specified by Gs2InventoryOwnItemSetContext. Canvas/InventoryWindow/Inventory/…/Content/Item/Icon Gs2InventoryItemModelNameEnabler Switches the GameObject to be enabled by the name of the assigned item model. For Potion, PotionImage is enabled; for Ether, EnterImage is enabled. As a result, the item icon changes depending on the type of item to be listed. Canvas/InventoryWindow/Inventory/…/Content/Item/Name Gs2InventoryItemModelLabel Formats the contents of the assigned item model in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InventoryWindow/Inventory/…/Content/Item/Count Gs2InventoryOwnItemSetLabel . Formats the contents of the assigned itemset in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/InventoryWindow/Inventory/…/Content/Item/Use/Gs2InventoryItemSetConsumeAction You can add a prefab from this context menu. Gs2InventoryItemSetConsumeAction . Consume Count allows you to specify the quantity to consume. By activating the prefab, the item specified in Gs2InventoryOwnItemSetContext will be consumed. Canvas/InventoryWindow/Input/Acquire Potion Gs2ExchangeRateModelContext Set the GS2-Exchange exchange rate at which GS2-Inventory Potion is obtained. Here we specify an exchange rate named Potion in the GS2-Exchange namespace named exchange-0001. Canvas/InventoryWindow/Input/Acquire Potion/Gs2ExchangeExchangeAction Gs2ExchangeExchangeExchangeAction . Count allows you to specify the quantity to be exchanged. By enabling prefabrication, the exchange specified in Gs2ExchangeRateModelContext will be executed. Canvas/InventoryWindow/Input/Acquire Ether Gs2ExchangeRateModelContext Set the exchange rate for GS2-Exchange to obtain Ether for GS2-Inventory. Here we specify an exchange rate named Potion in the GS2-Exchange namespace named exchange-0001. Canvas/InventoryWindow/Input/Acquire Ether/Gs2ExchangeExchangeAction Gs2ExchangeExchangeExchangeAction . Count allows you to specify the quantity to be exchanged. By enabling prefabrication, the exchange specified in Gs2ExchangeRateModelContext will be executed. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Inventory functionality using GS2 UIKit for Unity","title":"Sample of Inventory(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/inventory/"},{"content":"Add credentials Add Credentials to the project. The application can access various APIs by performing GS2-Identifier authentication using the client ID and client secret information contained in the credentials. Authentication is performed on a GS2-Identifier user basis. GS2-Identifier users have defined permissions to use GS2 services. This section describes how to add a user with access privileges for applications. Create User Select Identifier from the side menu of the Management Console and click Users. The “Identifier \u003e User List” page will open. Select Create New User on the right. The “Identifier \u003e User List \u003e Create New User” page will open. Enter the user name and description fields as appropriate, and click Create. (e.g. User Name: Application, etc.) Create Credential (API Key) On the “Identifier \u003e User List” page, select the user you just created. On the “Identifier \u003e User List \u003e User Information” page, add credentials for the user. On the Credentials tab, click Create New Credential. After clicking Create on the “Identifier \u003e User List \u003e User Information \u003e Credentials \u003e Create New Credential” page, a Client Id and Client Secret will be issued. Please keep the issued Client Id and Client Secret with you. Set Permissions for the User Assign a security policy to the newly created user. Here we assign the security policy ApplicationAccess, which is already defined as a standard application access policy. Click the Assign button for the security policy name ApplicationAccess in the Security Policy tab of the Identifier \u003e User List \u003e User Information page. The application is now ready to access the GS2 project.","lang":"en","section":"get_start","summary":"Creation procedure using the Management Console (Web UI)\n","title":"Management Console","url":"/get_start/tutorial/setup_credential/ui/"},{"content":"definition of terms term meaning Model Master data that does not change for each game player that is temporarily registered by the Master Data Editor model data that does not change for each game player that is used from within the game Properties Data that is different for each game player created based on the model Game elements include item parameters, quest composition data, and other data that does not change from player to player. There is data that does not change from one player to another, such as item parameters and quest composition data. Such data is called a model in GS2. The data that is transformed from models into data possessed by players is called properties. General master data corresponds to a model in GS2, and there is a concept of a model master in GS2. The difference between a model and a model master is that the content of the data is the same, but the difference is whether or not the data is actually accessible by the game. graph TD subgraph \"Data for Management\" Master[Model Master] end subgraph \"Data for Execution\" Model[Model] end subgraph \"Player Data\" Property[Property] end Master -- \"Export / Reflect (Current)\" --\u003e Model Model -- \"Instantiation\" --\u003e Property Data that can be edited on the GS2 administration screen is a model master, and when it is converted to a state that can actually be used in the game, it becomes a model. The reason this conversion process is necessary is so that all changes to the model master are reflected in the game at once. Without this process, data updated in the administration screen will be reflected in the game. Create master data This conversion process is a mechanism for exporting all model masters to JSON format files and uploading the JSON files to reflect them as models all at once. You can use the model masters by manipulating them on the GS2 Administration screen and exporting them to JSON format files, or you can create your own management tool, such as Excel, and reflect the data in models without registering any model masters on GS2. You can also manage master data in GS2 Deploy templates. In this case, it will be easier to use version control tools such as git, so please consider this option as well. Please manage master data in a way that is convenient for your organization. Freeze master data To avoid inconsistencies when a player updates his master data while logged in, a mechanism is provided to fix the master data used by the player as of a certain date and time. gs2 = await gs2.Distributor.Namespace( \"namespace-0001\" ).Me( _gameSession ).FreezeMasterDataAsync(); Thus, by calling GS2-Distributor’s FreezeMasterData, it is possible to process subsequent APIs with the contents of the master data at the time this API is called. However, it is possible to fix the master data within 30 days and up to 10 generations ago for each microservice. If this limit is exceeded, the latest master data will be used. Since WebSocketSession can be connected continuously for 2 hours, it is recommended to remobilize the connection when reconnecting when OnDisconnect of WebSocketSession is called. When re-fixing, check GS2-Version, etc., to see if the master data has been updated, and if so, consider returning to the title screen. Tip Recommended implementation for GS2-Version to determine if master data has been updated Register the master data version as warningVersion in the VersionModel in the format YYYY.MMDD.HHMM at the time of master data update. When the client reconnects to the WebSocketSession, it performs a version check using the date and time when the master data was fixed. If the warning is caught, it means that the master data has been updated, so the client should re-fix the master data at the current time while maintaining consistency by returning to the title, etc.","lang":"en","section":"articles","summary":"General specification of master data to be set up in GS2 microservices.\n","title":"Master data management","url":"/articles/master_data/"},{"content":"In this article, I would like to explain some of the mindset changes that are necessary when designing a long-running game. In particular, I will focus on what I have found to be misunderstandings in designing monetization for long-running games in my discussions with game developers in the US and Europe. Players buy time Let me explain the most important thing first. The monetization of long-running games is basically buying “time. On the first day of distribution, I heard people say, “I was going to play the game until I cleared it, but I didn’t have enough stamina and was required to pay for it. I often hear people say, “What a terrible game! However, that is to be expected. We want people to play long-running games for 15 to 30 minutes a day, every day; games that can be cleared in a day will be uninstalled after a week because there is nothing to play. If you are a game developer, you understand how difficult it is to create 10 hours worth of content in 3 months. But from the player’s point of view, if they have to wait 3 months, they usually forget about it. So you set a limit and make the time players have to wait as short as possible. On the other hand, it is too much to play every day and not catch up to the front of the pack. It is a good idea to allow new players to catch up to the leader after 1-3 months of play and challenge the end content. Now, here comes the business part. If it is a monthly subscription game, you can provide the service according to the principles so far. However, if you are providing a F2P style service, you need to take a different perspective. Even if you prepare content that can be played for 3 months at launch, there are players out there who would like to shorten that content to 3 days, even if they have to pay for it. Those players will almost certainly be gone after 3 months, but if they are willing to spend more than the typical lifetime value during the 3 days, we are willing to allow it. Monetization of long-running games should be designed with this point in mind. Gacha is free to spin The most misunderstood element of Japanese-style smartphone games is “Gacha”. “Gacha” is the “you don’t know how much it will cost to get what you want.” This is true in one sense, but wrong in another. What is important here is that “what you want” is not essential to playing the game. New characters are added every month and every week in Japan, but the number of players who have all of them is infinitesimally small. But the game can still be played well enough. Japanese-style smartphone games let you play Gacha for free every once in a spin. It might be a reward for completing a quest for the first time, a daily mission, an event reward, or an apology for interrupting gameplay for maintenance. In any case, just by continuing to play, $100 worth of money is surely paid out by the management every month. That is enough to get enough characters to play the game. Also, the hard-to-get characters may have high maximum parameters, but they are also designed to be difficult to grow. In fact, it is often the case that “it is actually stronger to develop the easy-to-obtain characters well.” Competing against each other is not important. In fact, it may be evil The first thing that comes to mind as the element that attracts players the longest in end content is the PvP element. However, in Japan, long-running games with PvP elements are rare. This is because PvP can be a mechanism that discourages weak players from playing the game. End content should be a mechanism to keep players playing for a long time, and it is meaningless if players leave the game because of this mechanism. PvP should not forget that the majority of participants will lose and feel bad. In a battle royale game, the player who survives to the end gets the best of it, but many other players may want to smash their desks. Think about it calmly. Would you be willing to smash a desk to keep playing that game for years? There are a lot of players who want a fun, leisurely, long-running game, and making the game for those players is better suited to long-term management.","lang":"en","section":"design_knowledge","summary":"to design monetization for Live Game, developers need to make many mindset changes","title":"What you must first change your mindset to monetize your Live Game","url":"/design_knowledge/change_your_mind/"},{"content":"Trends For a long time, the monetization trend in Japanese smartphone games has been to obtain characters through gacha, a game in which players are charged currency in order to draw gacha. For this reason, the majority of games offered only chargeable currency as well as items for sale that could be purchased with real money in the game. However, in recent years, sales styles that offer a full lineup of products have become more common. Billed currency has become the coordinator of cash value conversion What exactly does “enhanced product lineup” mean? Stamina recovery items + currency Training materials + currency SSR confirmed gacha tickets + currency Specifically, the above lineup is increasing. Behind these changes, we can see the intention to offer benefits that are less random and more immediately effective to players. Moreover, by offering bundles of special value packs of items such as SSR confirmed gacha tickets and training materials that can considerably streamline game progression, and by selling them for a limited time as the game progresses, we are increasing player satisfaction while increasing the desire to pay. The key here is that the bundle includes the currency used to pay for the game. Stamina recovery items, training materials, and gacha tickets are all bundled items that do not take effect immediately until they are used by the player. Under the Funds Settlement Law’s prepayment method, in-game items that do not take effect immediately are required to be converted in value, and the balance must be strictly managed and deposited so that it can be refunded at the end of service. However, by selling bundles alongside the sale of individual currencies, and by matching the balance between the amount of money and the number of currencies granted, it is possible to offer a wide range of items that are not immediately effective, such as By selling bundles next to single currency sales and matching the balance between the amount of money and the number of currency items, it is possible to build a structure that says, “Items such as stamina recovery items, training materials, and gacha (gacha) tickets are extras and have no monetary value. This structure allows players to flexibly decide which items to bundle without considering the timing of the effect of the items to be handled. Change in player experience As bundle sales increase, the way the charged currency is viewed will change. In my personal experience, contrary to the legal interpretation of the Funds Settlement Law, the charged currency starts to feel like an extra. If you buy bundle packs that include in-game items you want, you will gradually feel like you are accumulating billable currency. When players are running the gacha with the mindset of “I’ve accumulated enough billing currency from buying what I want, so let’s run the gacha,” they feel less psychologically damaged even if they don’t get SSRs. This may have other effects in increasing player satisfaction and engagement for a longer period of time. Billing Pressure Time-limited sales are perceived by players as billing pressure. It is important to pay attention to the frequency of their appearance and implement them. Be aware of the law of jams The marketing theory of “Jam’s Law” is important to keep in mind. This law states that the more choices a consumer has, the less willing he or she is to purchase. Since you can now bundle everything, it may be counterproductive to offer a large number of packaged products bundled with various items that players may want. Disclaimer GS2 is not responsible for the legal interpretation of the Funds Transfer Law mentioned in this article. Please check with your legal advisor for the official interpretation of the law. 2023-10-06 Kazutomo Niwa","lang":"en","section":"design_knowledge","summary":"monetization trends for 2020 and beyond","title":"Monetization Trends in Recent Years","url":"/design_knowledge/japanese_metagame/trends/"},{"content":"This sample implements balance management of billed currency. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Money GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Money/initialize_money_template.yaml Project Description Open the project and you will see the above. When executed, the balance of the billing currency will be displayed as shown here. First, click “Deposit(Free)”. Your balance will be 1000. Next, click “Deposit(Paid)”. Your balance will be 2000. Internally, free and paid are treated as separate data, but this sample shows the total amount. Next, click “Withdraw”. The balance will be 1900. Project Description Note the hierarchy of the scene. Canvas/MoneyWindow Gs2MoneyOwnWalletContext Specifies the GS2-Money wallet to be handled by the node under this GameObject. This time, we specify a slot 0 wallet in the money-0001 namespace of GS2-Money. Canvas/MoneyWindow/Wallet/Contents/WalletValue Gs2MoneyOwnWalletEnabler Enables the Value GameObject when the wallet specified in Gs2MoneyOwnWalletContext finishes loading. Canvas/MoneyWindow/Wallet/Contents/WalletValue/Value Gs2MoneyOwnWalletLabel . Formats the wallet specified by Gs2MoneyOwnWalletContext in the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/MoneyWindow/Input/Withdraw/Gs2MoneyWalletWithdrawAction Reduce the balance of the charged currency. Gs2MoneyWalletWithdrawAction . Specify the quantity to be consumed in Count. OnWithdrawComplete(EzWallet): Callback is returned when consumption is complete. Canvas/MoneyWindow/Input/DepositFree Gs2ExchangeRateModelContext Sets the GS2-Exchange exchange rate at which GS2-Money free currency is added. Here we specify the exchange rate named Gem0to1000 in the GS2-Exchange namespace named exchange-0005. Canvas/MoneyWindow/Input/DepositFree/Gs2ExchangeExchangeAction Adds the balance of the free billing currency. Gs2ExchangeExchangeExchangeAction . Specify the quantity to be exchanged in Count. Canvas/MoneyWindow/Input/DepositPaid Gs2ExchangeRateModelContext Sets the GS2-Exchange exchange rate at which GS2-Money paid currency is added. Here, the exchange rate named Gem1000to1000 in the namespace named exchange-0005 of GS2-Exchange is specified. Canvas/MoneyWindow/Input/DepositPaid/Gs2ExchangeExchangeAction Adds the balance of the paid billing currency. Gs2ExchangeExchangeExchangeAction . Specify the quantity to be exchanged for Count. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Money functionality using GS2 UIKit for Unity","title":"Sample of Money(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/money/"},{"content":"This sample implements the functionality of selling charged currency. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/MoneyStore GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/MoneyStore/initialize_money_store_template.yaml Project Description Open the project and you will see the above. When executed, you will see a list of items for sale as shown here. Click “Buy” for “¥100 x100”. The balance is now 100. This is not displayed in the Editor, but the payment sequence is interrupted when executed on iOS or Android. Project Description Notice the hierarchy of the scene. Canvas/MoneyStoreWindow/Wallet Displays the balance of the billed currency. Money sample , please refer to the explanation there. Canvas/MoneyStoreWindow/Store Gs2ShowcaseShowcaseContext Specifies the GS2-Showcase display shelf to be handled by the node under this GameObject. This time, we specify a display shelf named GenStore in the GS2-Showcase showcase-0001 namespace. Gs2ShowcaseShowcaseFetcher . Gets the information of the showcase specified by Gs2ShowcaseShowcaseContext. Canvas/MoneyStoreWindow/Store/…/Content Gs2ShowcaseDisplayItemList Generates the items displayed on the display shelves obtained by Gs2ShowcaseShowcaseFetcher by assigning them to the specified prefabs. Maximum Items specifies the maximum number of prefabs to be generated. This time, DisplayItem in the child node is specified as a prefab. If a GameObject specified as a prefab exists in the scene, that GameObject will be disabled and the number of GameObjects specified in Maximum Items will be created in addition to the GameObjects specified as prefabs. Canvas/MoneyStoreWindow/Store/…/Content/DisplayItem Gs2ShowcaseDisplayItemContext Specifies the item to be handled by the node under this GameObject. The content of the context is assigned by Gs2ShowcaseDisplayItemList. Gs2ShowcaseDisplayItemFetcher Gets the details of the displayed item. Canvas/MoneyStoreWindow/Store/…/Content/DisplayItem/Icon Gs2ShowcaseSalesItemNameEnabler Controls the display and hiding of GameObjects using the name of the displayed item. It is used to switch the displayed image depending on the product. Canvas/MoneyStoreWindow/Store/…/Content/DisplayItem/Price Gs2MoneyDepositByUserIdFetcher . Gs2MoneyDepositByUserId from DisplayItem’s AcquireActions. Gs2MoneyDepositByUserIdLabel . formats the parameters set in Gs2MoneyDepositByUserId into the format specified in Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/MoneyStoreWindow/Store/…/Content/DisplayItem/Count Gs2MoneyDepositByUserIdFetcher . Gs2MoneyDepositByUserId from AcquireActions in DisplayItem. Gs2MoneyDepositByUserIdLabel . formats the parameters set in Gs2MoneyDepositByUserId into the format specified in Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Canvas/MoneyStoreWindow/Store/…/Content/DisplayItem/Buy/Gs2ShowcaseShowcaseBuyAction You can add a prefab from this context menu. Gs2ShowcaseShowcaseBuyAction . You can specify the quantity to be purchased in Quantity. By activating the prefab, the item specified in Gs2ShowcaseDisplayItemContext will be purchased. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Money + GS2-Showcase functionality using GS2 UIKit for Unity","title":"Sample of MoneyStore(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/money_store/"},{"content":"This sample implements a function to sell a charged currency with a sale weight with a limit on the number of purchases. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/MoneyStoreWithSale GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/MoneyStoreWithSale/initialize_money_store_with_sale_template.yaml Project Description Open the project and you will see the above. When executed, the project shows a display of products with a limited number of purchases, unlike the MoneyStore sample. Click on “Buy” for “¥10000 x 16000”. The purchase limit is reduced to 1/2 and the balance becomes 16,000. Buy again. The purchase limit is reduced to 2/2 and the balance becomes 32,000. The “Buy” button will be disabled because the maximum number of purchases has been reached. Project Description Notice the hierarchy of the scene. Canvas/MoneyStoreWindow/Wallet The balance of the billed currency is displayed. Money sample , please refer to the explanation there. Canvas/MoneyStoreWindow/Store Displays a display shelf for charged currency. The basic implementation is shown in MoneyStore sample . From here on, only the differences from the MoneyStore sample are explained. Canvas/MoneyStoreWindow/Store/…/DisplayItem Gs2LimitCountUpByUserIdEnabler If Gs2LimitCountUpByUserId is set in ConsumeActions of DisplayItem, EnableLimit is enabled, otherwise DisableLimit is enabled. Canvas/MoneyStoreWindow/Store/…/DisplayItem/EnableLimit Gs2LimitCountUpByUserIdFetcher . Gets the Gs2LimitCountUpByUserId set in ConsumeActions of DisplayItem. Gs2MoneyDepositByUserIdFetcher . Gets Gs2MoneyDepositByUserId set in AcquireActions of DisplayItem. Canvas/MoneyStoreWindow/Store/…/DisplayItem/EnableLimit/PriceAndRemain/Remain Displays the number of remaining purchases available. Gs2LimitOwnCounterFetcher . Gets the value of the counter for the consumption action obtained by Gs2LimitCountUpByUserIdFetcher. Gs2LimitCounterEnabler Enables CounterLoadingText or CounterLoadedText depending on whether the counter has been retrieved by Gs2LimitOwnCounterFetcher. Canvas/MoneyStoreWindow/Store/…/DisplayItem/EnableLimit/Buy ConsumeActionsEnabler . Enables Active or InActive depending on whether the consume actions set in the DisplayItem’s ConsumeActions meet the execution conditions. This component disables the Buy button when the maximum number of purchases is reached. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Money + GS2-Showcase + GS2-Limit functionality using GS2 UIKit for Unity","title":"Sample of MoneyStoreWithSale(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/money_store_with_sale/"},{"content":"On the GS2 official YouTube channel, we publish explanatory videos for each microservice, walkthroughs of the sample implementations, and information related to operating GS2. Game Server Services EN","lang":"en","section":"articles","summary":"Official YouTube Channel Introduction.\n","title":"Official YouTube Channel","url":"/articles/sample/youtube/"},{"content":"GS2 allows multiple accounts that can be logged in from the management console for project management. Creating users for login First, add a User to GS2-Identifier for each login user. Enter a user name and create the user. Set permissions for the user Set appropriate permissions for the user. For more information on security policies, see Access Control for more information. Set password for user Select the user you created. Select the Password tab. Create a password. Confirm login URL The information in the Password tab contains the URL to log in to the management console as this user.","lang":"en","section":"articles","summary":"How to manage one project with multiple developers.\n","title":"Project Sharing","url":"/articles/project/share/"},{"content":"GS2 currently offers services in 4 regions. Name Region ap-northeast-1 East Asia us-east-1 North America eu-west-1 Europe ap-southeast-1 Asia Zones One region consists of two zones. name country/region of deployment ap-northeast-1 Japan/Korea us-east-1 United States (Virginia and Oregon) eu-west-1 Ireland/Germany ap-southeast-1 Singapore/India Zones are configured as Active / Active, with the zone closest to the game player being used. Between zones, databases are synchronized in real time, but with a delay of less than 1 second. Zones may switch automatically when the access source physically moves or when there is a failure that renders a zone unusable. In such cases, there may be a slight “write should have completed, but when read, the result is not reflected” moment. GS2’s SDK for the Game Engine caches data retrieved from the server in the SDK layer, and once the data is retrieved, the cache is automatically updated to the latest state when the server data is updated. This mechanism is designed so that games can call the GS2 SDK API with high frequency without worrying about communication time or cost for read requests, and the cache is designed to reflect the latest information on a best-effort basis when switching zones. Game developers should not hesitate to call the GS2 SDK’s loading API to reflect values in the UI, not only when switching scenes, so that This allows game developers to focus on game development by reflecting the latest values in the UI without having to worry about delays when switching zones. Data Centers A zone consists of three data centers. The data centers are physically configured in separate locations, but are located less than 100km(60mi) apart. If one of the data centers becomes unavailable, no zone switchover will occur and services will continue to operate at the remaining two data centers.","lang":"en","section":"articles","summary":"About the regions of data centers available in GS2.\n","title":"Regions","url":"/articles/tech/region/"},{"content":"To start using Game Server Services, you must first register an account. Account registration can be done from the bottom of the page at https://gs2.io . During this phase, you will need to discuss the operational policy for the accounts that developers will use. Each developer creates a dedicated account for development Developing with a shared account Each developer creates a dedicated account for development GS2 recommends this method. By having each developer create a dedicated account and develop in a dedicated environment, development can proceed smoothly without being affected by other developers’ changes to GS2 settings. GS2 provides a way to share GS2 resource settings among developers, and by using this feature, a dedicated development environment can be maintained with minimal effort. Project \"1\" *-- \"many\" Developer Developer \"1\" -- \"1\" Gs2Account Gs2Account \"1\" *-- \"many\" Gs2Project Gs2Project \"1\" *-- \"many\" GS2Resources Cost may also be a concern with this method. GS2 uses a pay-as-you-go billing model, so there are no additional costs as the number of accounts or projects grows. We will explain how to do this in a later step. Develop with a shared account Create a GS2 account for your project, or a development GS2 account, and create a development project within that account. For each project, you can create sub-accounts that have access to the project’s administrative functions, allowing multiple people to manage a single project using this mechanism. Project \"1\" *-- \"1\" \"Gs2Project(Dev Env)\" \"Gs2Project(Dev Env)\" \"1\" *-- \"many\" User User \"1\" -- \"1\" LoginPassword User \"1\" -- \"1\" Developer","lang":"en","section":"overview","summary":"GS2 Account Registration Procedure and Operation Policy\n","title":"Register a GS2 account","url":"/overview/workflow/setup_gs2/create_account/"},{"content":"We provide sample code and learning resources to help you develop games with GS2. Please use the appropriate resources depending on your learning goals and development phase. Choosing a sample Sample Contents Recommended use GS2 Implementation Sample A comprehensive Unity sample that covers a wide range of features When you want to understand how GS2 features work together and see typical game-loop implementations UIKit-based Samples Minimal samples per feature, built on UIKit When you want to look at the implementation of a specific feature such as account, inventory, or chat Official YouTube Channel Feature overviews and tutorial videos When you want to follow screen transitions and configuration steps that are hard to convey through text alone The UIKit-based samples are split into per-feature repositories, so you can incrementally adopt only the parts you need into your own project. On the other hand, the GS2 Implementation Sample is intended as a reference implementation where multiple microservices are working together.","lang":"en","section":"articles","summary":"Introduction of sample code\n","title":"Sample codes","url":"/articles/sample/"},{"content":"To initialize the SDK, you need to create the Credential and Session objects. Credential An object representing a GS2 API key. The class BasicGs2Credential is defined and used when using the API with clientId / clientSecret. BasicGs2Credential Parameters Argument Name Description clientId Client ID clientSecret Client Secret Session There are two types of sessions: Gs2RestSession , which uses HTTP communication, and Gs2WebSocketSession , which uses WebSocket communication. Depending on the programming language, Gs2WebSocketSession may not be supported, and it also has limitations when handling requests with large payloads. Therefore, if push notifications from the server are not required, Gs2RestSession should be used as a general rule. Gs2RestSession Request Argument Name Description credential Credential object region GS2 Region to connect to Gs2WebSocketSession Request Argument Name Description credential Credential object region GS2 Region to connect to Initialization The created Session object must be connected before use by calling its connection API. Chaos mode By calling the SDK initialization process with chaos mode applied, API requests can be made to fail with a certain probability. Development can proceed using clients with chaos mode enabled to ensure robust error handling. Clients for microservices A client is provided for each of the various microservices offered by GS2. There are also clients for each communication protocol, such as Gs2AccountRestClient and Gs2AccountWebSocketClient , which require Gs2RestSession and Gs2WebSocketSession respectively. Gs2AccountRestClient Request Argument Name Description session Gs2RestSession Gs2AccountWebSocketClient Request Argument Name Description session Gs2WebSocketSession Implementation Example","lang":"en","section":"api_reference","summary":"how to initialize GS2-SDK","title":"SDK","url":"/api_reference/initialize/sdk/"},{"content":"About GS2-SDK for Game Engine transaction processing Please refer to the for Game Engine document for the basic concept and processing flow. On the other hand, GS2-SDK does not provide as extensive support as for Game Engine . Specifically, there is no cache function or EzTransactionDomain. Transaction Execution If auto-execution is enabled You must explicitly set a user ID on GS2-Gateway in order to receive completion notifications. GS2-Gateway::setUserId Need to handle completion notification. The Gs2WebSocketSession class provides notification handling functions, so use those. Some programming languages may not have a WebSocket client implementation. When you receive notification from GS2-Distributor that the transaction has completed execution, you must explicitly retrieve the results. The execution result may contain errors and the execution result may be updated until it succeeds. GS2-Distributor::getStampSheetResult Once you receive notification from GS2-JobQueue that the job has completed execution, you must explicitly retrieve the results. The execution result may contain errors, and since the latest result can be retrieved if tryNumber is not specified, you must use it and wait until it succeeds. GS2-JobQueue::getJobResult If auto-execution is disabled When calling a transaction issuing API such as GS2-Showcase::Buy, the stampSheet variable will respond with the transaction data and the stampSheetEncryptionKeyId with the ID of the encryption key used to calculate the signature of the transaction data The transaction data and the encryption key information are stored in the stampSheet variable. The transaction data and encryption key information must be passed to GS2-Distributor to explicitly execute the transaction. If you wish to log to GS2-Log, call runStampSheetExpress with the namespace of the GS2-Distributor that you have configured to export the log, or call runStampSheetExpressWithoutNamespace If not required, call runStampSheetExpressWithoutNamespace. GS2-Distributor::runStampSheetExpress GS2-Distributor::runStampSheetExpressWithoutNamespace If the result of running runStampSheetExpress or runStampSheetExpressWithoutNamespace contains stampSheet , that transaction must also be explicitly executed. If the action to obtain the stamp sheet was “Gs2JobQueue:PushByUserId”, then GS2-JobQueue must also be executed. GS2-JobQueue::run","lang":"en","section":"api_reference","summary":"GS2-SDK Transaction Processing","title":"SDK","url":"/api_reference/transaction/sdk/"},{"content":"There are three major categories of security requirements Tampering with game executables Tampering with memory during game execution Tampering with user data Tampering with game executable In this case, the attacker can change the attack power of a certain weapon from 10 to 9999 by cheating. In Android, this kind of attack is possible by disassembling the apk file, tampering with the game data, and creating a repackaged apk file. GS2 does not support this attack. This problem needs to be addressed by implementing a solution to detect if the game binaries have been tampered with. Memory tampering during game execution Rewriting memory information at runtime, for example, to illegally reduce enemy health or This is an attack that rewrites the value of the flag used to determine if a quest has been cleared, and puts the quest into a sequence in which it is cleared even though it should have failed. GS2 does not support this attack. It is necessary to address such problems by implementing a solution that detects if memory values have been tampered with during game execution. Tampering with user data This attack involves tampering with the quantity of items in the user’s possession. GS2 manages user data (saved data) such as the number of items possessed on the server side, and increases/decreases the number of items can be done via the API. In particular, GS2 is designed so that user data operations that are beneficial to the player, such as increasing the number of items, can only be manipulated through the side effects of the microservices provided by GS2. For example GS2-Showcase increases the number of items in a player’s possession when he/she purchases an item GS2-Quest increases the quantity of an item when a quest is completed The number of items in your possession can be increased only through processes such as the following. Purchasing an item in GS2-Showcase requires some kind of payment, such as spending in-game currency. Starting a quest in GS2-Quest requires paying some price, such as spending stamina. This design makes it impossible to perform the act of increasing items without limit.","lang":"en","section":"articles","summary":"GS2's Approach to Security","title":"Security","url":"/articles/security/"},{"content":"GS2-Account Regarding transferring information, the registration, update, and deletion of the same user’s information should be limited to three times per second. This limit does not apply to different users. GS2-Chat You can only post up to 3 times per second for one room. Please avoid implementing a system that allows an extremely large number of people to participate in a room, or that encourages people to post all at once. GS2-Experience Please limit experience to 3 times per second for the same property. This limit does not apply to different users or different properties for the same user. GS2-Formation Update the same form no more than 3 times per second. GS2-Friend No more than 3 profile updates per second by the same game player. This limit does not apply to different users or to the same user granting experience to different properties. Avoid concentrating friend requests on a single player. A player can only receive 3 friend requests per second. GS2-Inventory Please limit the number of times per second that you increase or decrease the amount of inventory for the same property. For operations that use up inventory items that are new to the inventory, even for different properties, please limit the number of operations in the inventory to 3 per second. If it is an increase or decrease in the possession quantity for a different property, this limit does not apply. GS2-JobQueue Please limit job submissions to the queue for the same user to no more than 3 per second. Up to 10 jobs can be registered per job registration, so please be creative. If the automatic execution function is not used, job execution should be limited to once per second. This limit does not apply if you are processing jobs for different users. GS2-Limit Please limit the number of operations on the same counter to 3 operations per second. This limit does not apply to operations on different users or different counters by the same user. GS2-Lock No more than 3 operations per second on the same mutex. This limit does not apply to operations on different mutexes. GS2-MegaField No more than 5 updates of coordinate information per second per user. GS2-Mission No more than 3 operations on the same counter per second. This limit does not apply to operations on different users or different counters for the same user. GS2-Money No more than 3 operations on the same wallet per second. This limit does not apply to operations on different users or different wallets of the same user. GS2-Script Scripts must be completed within 10 seconds. GS2-Stamina No more than 3 operations on the same stamina per second. This limit does not apply to operations on different users or different stamina models for the same user. GS2-StateMachine The number of state transitions for the same state machine is limited to 10,000. 10,000 transitions will result in an error response. Please limit the number of events sent to the same state machine to 3 per second.","lang":"en","section":"articles","summary":"Restrictions on the use of each GS2 microservice.\n","title":"Service Limitations","url":"/articles/service_limit/"},{"content":"The first thing a developer should do in the Management Console is to create a namespace and register master data. These can be created in the Management Console. Select Region Below the side menu, there is a region menu. From here you can select the region in which you want to operate microservices. Create a namespace Log in to the Management Console and select Microservices. When the list of namespaces appears, create a new namespace. Enter values in the configuration fields and confirm them to complete the creation of the namespace. Register master data Some microservices require master data to be registered before using their functions. For microservices that require master data registration, there is a tab titled “Master Data” on the namespace detail page. When you select the tab, you will see an error message like “Currently available master data could not be found,” indicating that master data has not yet been registered. Using the Master Data Editor The Master Data Editor can be used to create master data. Select the “Master Data Editor” tab on the namespace detail page. This screenshot is an example from GS2-Inventory. To illustrate the creation of master data, let’s explain what kind of master data GS2-Inventory needs. class InventoryModel { +string Name +int Initial size +int Maximum size } class ItemModel { +string Name +int Maximum stackable quantity +bool Allow items to be stored in multiple slots when the maximum stackable quantity is exceeded? +int display order } Namespace \"1\" *-- \"many\" InventoryModel InventoryModel \"1\" *-- \"many\" ItemModel GS2-Inventory requires the definition of an Inventory with a capacity limit and an Item that can be stored in the Inventory. The inventory has an initial capacity and a maximum capacity; the item specifies the maximum number of items that can be stacked in a capacity and whether a second stack is created when the number of items in the inventory reaches the maximum number of items that can be stacked. Creating an Inventory Model First, create an Inventory Model using the Master Data Editor. Enter values for each item and press the Create button. Once added to the list of Inventory Models, select the created Inventory Model to open the detail page. Creating an Item Model Once you open the Inventory Model detail page, the next menu item is to create an Item Model. Select it to create an Item Model. Enter values for each item and press the Create button. Exporting Master Data After registration, export the master data. Return to the namespace details page and select the Master Data Editor tab. Press the Export button at the top of the tab pane. A JSON file of the master data will be exported. Master data is managed in such a JSON file. Therefore, you do not necessarily need to use the Master Data Editor in the Management Console, but can prepare a program to export master data managed in a spreadsheet. The JSON format of the master data is described in detail in the programming guide for each microservice. Reflecting Master Data Select the “Master Data” tab again, where an error occurred earlier that there was no master data registered. Select the menu for uploading master data. Select the exported JSON file to upload. Reflection is complete when the master data is displayed. All microservices that require master data registration can register and update master data in this way.","lang":"en","section":"overview","summary":"Create a resource in a microservice using the Management Console.\n","title":"setup using the management console","url":"/overview/workflow/setup_gs2_resources/manual_setup/"},{"content":"Implement the Stamina function. Repository https://github.com/gs2io/gs2-uikit-for-unity-sample/tree/main/Stamina GS2-Deploy template https://github.com/gs2io/gs2-uikit-for-unity-sample/blob/main/Stamina/initialize_stamina_template.yaml Project Description Open the project and you will see the above. When executed, the remaining amount of stamina and the UI for stamina operations will be displayed as shown here. First, click the “Consume(5)” button. Having consumed stamina, the remaining amount is displayed as “45/50” and a countdown is shown until it is recovered. Next, click the “Recover(10)” button. The remaining amount of stamina will be “55/50”. The countdown will not be displayed again because the maximum value has been exceeded. Project Description Note the hierarchy of the scene. Canvas/StaminaWindow Gs2StaminaOwnStaminaContext Specifies the stamina of GS2-Stamina handled by the node under this GameObject. In this case, we specify a stamina named Stamina in the namespace stamina-0001 of GS2-Stamina. Canvas/StaminaWindow/Stamina Gs2StaminaStaminaEnabler After loading the Stamina, activate StaminaValue. Canvas/StaminaWindow/Stamina/StaminaValue/Slider Gs2StaminaStaminaProgress . Gets the percentage of the current stamina value relative to the maximum value, from 0.0 to 1.0. The value is rounded to 1.0 when the maximum value is exceeded. The result obtained is passed to OnUpdate(Single) and reflected in the Slider value. Canvas/StaminaWindow/Stamina/StaminaValue/Slider/Label Gs2StaminaOwnStaminaValueEnabler . Enables a GameObject based on whether the maximum value of stamina has been reached. Canvas/StaminaWindow/Stamina/StaminaValue/Slider/Label/NextRecoverAt Gs2StaminaOwnStaminaNextRecoverAtFetcher . Gets the date and time when stamina will be restored next time. The result is called back to OnUpdate(int64) and the value is reflected in Gs2CoreTimeSpanLabel. Gs2CoreTimeSpanLabel . Formats the remaining time until the next recovery of stamina into the format specified by Format. The formatted text is called back to OnUpdate(String), from which the value is reflected in the Text component. Process/Gs2AutoLogin A prefab is set up to perform the login process. sample of Account , please refer to the explanation there.","lang":"en","section":"articles","summary":"sample implementation of GS2-Stamina functionality using GS2 UIKit for Unity","title":"Sample of Stamina(GS2 UIKit for Unity)","url":"/articles/sample/uikit_project/stamina/"},{"content":"GS2 uses a transaction system called “Stamp Sheets” to link services. Among the APIs in GS2, operations that are disadvantageous to the player are called “Consume Action”, while operations that are beneficial to the player are called “Acquire Action”. Let’s say there is an action in the game store to “Spend 1000 Gems” and “Draw 10 times in the Gacha”. In this case, “Spend 1000 Gems” can be considered a “Consume Action” and “Draw 10 times in the Gacha” can be considered an “Acquire Action”. Let’s look at a few more examples. Execute the “Read Message” consume action and then execute the “Receive 100 Gems attached to the message” acquisition action. Performing the “Consume 10 Stamina” consume action and then performing the “Set Quest 1 as Started” acquisition action Perform a “Delete Quest 1 Started” consume action to “Receive the reward for clearing Quest 1” acquisition action. Execute the “Update Last Idle Reward Receiving Time with Current Time” consume action to “Get the reward according to the idle time” acquisition action. Perform a consume action to “Raise the daily reset counter by 1” to “Obtain an item that cannot be received more than once a day” to perform the “Obtain an item that cannot be received more than once a day” action. Thus, in GS2, every game cycle is represented by consuming something and getting something. How Stamp Sheets Work A stamp sheet consists of several “Consume Actions” and one “Acquire Action”, Stamp sheets are issued by GS2 microservices such as the Store and Quest functions. The contents of the stamp sheet are determined based on the product master data registered in the store function. Stamp sheets are executed by Execution of \"Consume Action\" -\u003e Execution of \"Acquire Action\" The stamp sheets are processed in this order. This order of processing prevents unauthorized repeated execution of the “Acquire Action”. When the “Consume Action” is executed, the microservice that provides the GS2 functionality will issue a signature to prove that it has been executed. When a “Acquire Action” is executed, the signatures received from all “Consume Actions” are sent together. Signature verification is performed before executing the “get action” to ensure that everything has been done before executing the “get action”. Service Discovery Depending on the contents of the “Consume Action” or “Acquire Action” on the stamp sheet, the appropriate microservice must be requested to perform the processing. However, GS2’s functionality is constantly being added, and the number of “Consume Action” and “Acquire Action” types continues to increase, making it difficult to maintain such branching processes. For this reason, GS2 provides GS2-Distributor, a microservice that forwards the received stamp sheets to the appropriate microservice. By sending a stamp sheet to GS2-Distributor, GS2-Distributor is responsible for forwarding the sheet to the appropriate microservice according to the “Consume Action” or “Acquire Action” on the stamp sheet. Preventing duplicate executions Stamp sheets are designed in such a way that they cannot be duplicated. In fact, all GS2 Consume Actions and Acquire Actions APIs have a mechanism to prevent duplicate execution. The “Consume Action” and “Acquire Action” APIs accept a “Duplication Avoider” parameter. If a value is specified here and the API completes successfully, the response will be saved by GS2 for a certain period of time. If the “Duplication Avoider” is specified in the same request payload, and if a process with a matching “Duplication Avoider” value has been executed in the past, the response will be treated as a normal completion and no processing will actually take place. In addition, when executing a “Consume Action” or “Acquire Action” using a stamp sheet, the “Duplication Avoider” should be set to “Transaction ID,” which is a unique ID for the stamp sheet. Let’s take a step-by-step look at how the duplication prevention mechanism works. Suppose we have the following stamp sheet: Consume Actions Consume 1 item Increase the daily limit counter by 1 Acquire Action Obtain 10 Gems When executing this stamp sheet, the process follows these steps: Execute “Consume 1 item” 1 item is consumed. A record is stored on the server: “Transaction ID XXX: Item consumption successful.” Execute “Increase the daily limit counter by 1” Suppose a network error or server error occurs here, and the process is interrupted. At this point, the item has already been consumed, but the player hasn’t received the gems yet — a disadvantageous state for the player. Retry the Stamp Sheet The stamp sheet is re-executed from the beginning, either by the client or by server-side automatic execution. It attempts to execute “Consume 1 item” again, but this is where the Duplication Avoider kicks in. Since there is already a record of success, it does not actually perform the consumption again but simply returns the previous successful response. Retry “Increase the daily limit counter by 1” This step failed previously, but this time it succeeds normally. A record of success is stored on the server. Execute “Obtain 10 Gems” Finally, the acquisition action is executed, gems are granted, and the process is complete. As you can see, the side executing the stamp sheet doesn’t need to manage exactly how far the process went. If it fails, it can simply “start over from the beginning,” and the Duplication Avoider ensures the final state is reached without any inconsistencies. Automate stamp sheet retries Although we have said that you should retry when a stamp sheet fails to execute, it is actually difficult to do so thoroughly, even though it sounds simple. Therefore, the GS2 microservice that issues stamp sheets has an option called “Automatically execute stamp sheets”. If this option is enabled, the server side will automatically retry when a retry is necessary for some reason. If the retry does not solve the problem, such as “not enough items left to spend in the consume action,” the retry may not be performed. Multiple Acquire Action You may think that multiple Acquire Action are acceptable if there is a mechanism to prevent duplicate execution. That is basically correct. However, it is important to note that the retention period for response content to prevent duplicate execution is not indefinite. If the retention period for response content is exceeded, it will be possible to execute a stamp sheet issued in the past again. In this case, it is still necessary to execute the consume action, but even if the consume action is executed, there are cases where it is undesirable to execute it again. To address this problem, a process is incorporated to invalidate the stamp sheet itself when the stamp sheet execution is completed, so that it cannot be re-executed even if the response content retention period has passed. If there are multiple “obtain actions” here, it will be difficult to know when to deactivate the stamp sheet. For this reason, the stamp sheet is designed so that only one “Acquire Action” can be set. However, as a practical matter, it is not always possible to have only one acquisition action in a game. Even in the most common game cycle, the quest function, two Acquire Action occur at the same time: “gain experience” and “drop item acquisition. To handle such cases, GS2 makes use of job queues. A job queue is a queue prepared for each player for delayed execution. In a situation where you want to set up a “get action” on a stamp sheet, you set up a single “get action” by “registering multiple jobs to perform get actions in the job queue”. This process is automated, and multiple “Acquire Actions” can be set when setting up rewards in the quest master data. When issuing a stamp sheet, this is transformed into “registering multiple jobs to perform an acquisition action” and the stamp sheet is issued. Stamp sheet execution is an asynchronous process As we have seen, it is very difficult to wait for a stamp sheet to complete. GS2 provides a number of microservices, and even if one of them stops, the entire service is designed not to stop. However, when a failure occurs, the execution of stamp sheets and job queues stalls, and there is no guarantee that the results will be reflected immediately. On the other hand, when a failure is restored, you do not have to do anything, but the stamp sheet and job queue will retry and the process will begin to flow, and eventually normalize. You may be puzzled because this is different from the conventional development style. However, GS2 adopts this design for the overall benefit that even if a temporary inconsistency occurs due to a partial microservice failure, the process will eventually be normalized after the failure is restored without having to think about it. Setting Parameters when Issuing Stamp Sheets Requests to each service require information about which user’s resources are to be manipulated, though, However, it is not possible to statically specify user IDs in advance in the in-game store or quest master data. Therefore, a variable can be embedded in the stamp sheet request. If you set the placeholder string #{userId} in the request for the master data action, This will be replaced by the user ID of the user who issued the stamp sheet when the stamp sheet is issued. Config A parameter called Config(EzConfig) can be passed to the stamp sheet issuance request. Config(EzConfig) is a key/value format that allows you to replace the placeholder string #{key value specified in Config} with the passed parameter. Example of a stamp sheet that adds a balance to a wallet . { \"name\": \"currency-120-jpy\", \"metadata\": \"price: 120 currencyCount: 50\", \"consumeActions\": [ { \"action\": \"Gs2Money:RecordReceipt\", \"request\": \"{\\\"namespaceName\\\": \\\"money-0001\\\", \\\"contentsId\\\": \\\"io.gs2.sample.currency120\\\", \\\"userId\\\": \\\"#{userId}\\\", \\\"receipt\\\": \\\"#{receipt}\\\"}\" } ], \"acquireActions\": [ { \"action\": \"Gs2Money:DepositByUserId\", \"request\": \"{\\\"namespaceName\\\": \\\"money-0001\\\", \\\"userId\\\": \\\"#{userId}\\\", \\\"slot\\\": \\\"#{slot}\\\", \\\"price\\\": 120, \\\"count\\\": 50}\" } ] } Example of setting Config values from Unity var result = await gs2.Showcase.Namespace( namespaceName: \"namespace-0001\" ).Me( gameSession: GameSession ).Showcase( showcaseName: \"showcase-0001\" ).BuyAsync( displayItemId: \"display-item-0001\", quantity: 1, config: new [] { new EzConfig { Key = \"slot\", Value = Slot.ToString(), }, new EzConfig { Key = \"receipt\", Value = receipt, }, } ); Result of execution of 《Consume Action》 on the stamp sheet If you set the placeholder string %{Gs2Money:WithdrawByUserId.price} as an example in the description of the action request, The placeholder string will be replaced by the result of the stamp task execution and can be used as a variable. In the case shown in the example, the result of the Gs2Money:WithdrawByUserId execution of the executed task is referenced and the returned price is used as the value. Child elements can be referenced by connecting them with dots like %{Gs2Money:WithdrawByUserId.item.paid} . The value adopted when the same action is registered as multiple stamp tasks is undefined.","lang":"en","section":"articles","summary":"description of Game Server Services transaction system, Stamp Sheets","title":"stamp sheet","url":"/articles/tech/stamp_sheet/"},{"content":"SDK Game Engine Game Server Services provides SDKs for all major game engines. The SDK for game engines is provided in a higher level API format than the regular SDK, with a focus on use from within the game. Various programming languages You can use GS2 with various programming languages, including Go, PHP, Java, C#, TypeScript, and Python. You can download the source code from GitHub or obtain it through the respective package managers. CDK CDK stands for Cloud Development Kit, a development kit that enables GS2 orchestration in code. To explain the functionality more concretely, you can write code to instantiate an object corresponding to a GS2 resource in the CDK and call the Dump API to generate a GS2 Deploy template. GS2-Deploy templates can be written in YAML format, but because YAML files are not program code, they cannot import external files or execute loops, and to optimize the workflow it was necessary to write code to generate templates. CDK is a solution to streamline such a workflow, allowing you to parse master data Excel files and generate GS2-Deploy templates while defining event durations in a loop within the tool using CDK. Have you finished installing the SDK? Next, let’s try the Tutorial to see GS2 in action.","lang":"en","section":"get_start","summary":"How to start using Game Server Services.\n","title":"Start using GS2","url":"/get_start/"},{"content":"This section gathers technical documentation that helps you understand GS2 in depth and make design decisions when integrating it into your game. It covers cross-cutting mechanisms and best practices that are not described in the individual API references or per-microservice manuals. Sections Section Contents Region Region / zone topology of GS2 data centers and the resulting consistency model Access Control Users and security policies of GS2-Identifier Stamp Sheet How the GS2 transaction system, the Stamp Sheet , works Transaction Settings The meaning of TransactionSetting on namespaces and recommended values GS2-Deploy Template File Specification The template file format used with GS2-Deploy Errors and Exceptions API error structure, SDK exception types, and how to decide when to retry SDK Cache Mechanism How the SDK caches data internally and how to take advantage of it Cost Optimization Design tips for keeping costs down while preserving performance Related sections Master Data Management : The model / model master distinction and how to freeze master data Service Limits : Rate limits on API calls for each microservice Security : The GS2 security model and the parts that must be handled by the game side Utility methods of GS2-Script : Built-in Lua functions available in GS2-Script","lang":"en","section":"articles","summary":"Technical Documentation for a deeper understanding of GS2.\n","title":"Technical Documentation","url":"/articles/tech/"},{"content":"The microservices provided by GS2 generally have a field named TransactionSetting in their namespace configuration. TransactionSetting has the following structure:  enableAutoRun bool  false Execute the issued transaction automatically on the server side enableAtomicCommit bool {enableAutoRun} == true  false Commit the transaction atomically Required if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true  false Execute transactions asynchronously Required if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true  false Execute the script’s result commit processing asynchronously Required if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true  false When executing the get action, use GS2-JobQueue if enableAtomicCommit is true distributorNamespaceId string  “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 characters The GS2-Distributor namespace used to execute transactions queueNamespaceId string  “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 characters The namespace of the GS2-JobQueue used to execute transactions Field Explanation enableAutoRun Configures whether issued transactions are automatically executed. There is almost no reason to set this to false nowadays. In the past, GS2 lacked a mechanism for automatically executing transactions. The primary method for executing transactions involved manually requesting and processing issued transactions with each microservice. However, this approach only complicates error handling when transactions fail midway. enableAtomicCommit The AtomicCommit feature is a relatively recent addition within the history of GS2’s transaction system. Before AtomicCommit existed, issued transactions were executed asynchronously. For example, when calling the product purchase API in GS2-Showcase, the purchase process wasn’t complete at that stage. Only after the result of the asynchronously executed transaction was returned could you determine whether the transaction succeeded or failed. The challenge with this design lay in what happened when an error occurred during transaction execution. The auto-execution mechanism works like this: after a consumption action succeeds, if an acquisition action fails but the failure is a server error worth retrying, the server automatically attempts a retry to complete the transaction. However, if the acquisition action fails due to exceeding the allowed quantity, or if one of multiple configured consumption actions fails due to insufficient resources, the transaction fails at that point. Yet, the successful consumption action might still be executed. AtomicCommit was introduced to solve this problem. It executes consumption and acquisition actions before returning the response from the GS2-Showcase item purchase API. Only if all actions succeed will the results be reflected in the database. Enabling this setting prevents transactions from executing in an incomplete state. Therefore, we strongly recommend enabling AtomicCommit when developing new games using GS2. However, AtomicCommit is not a panacea. Since it executes consumption and acquisition actions concurrently, attempting to update the same resource within the same action will result in an error. Note that AtomicCommit cannot be enabled when executing such transactions. Furthermore, enabling AtomicCommit extends its effect not only to transaction execution but also to pre-scripts executed via that API. For example, if you have a script configured for product purchases, any operations within that script that call the GS2 API to modify data, or transactions initiated by the script, will have their results reflected when the GS2-Showcase product purchase API succeeds. transactionUseDistributor This option is available when enableAtomicCommit is enabled. This setting configures transaction execution to be asynchronous. When enabled, consumption and acquisition actions are processed as AtomicCommit, but the GS2-Showcase item purchase API returns a response without waiting for their completion. It is intended for use when waiting for transaction results is unnecessary, or when there is a conflict between the data rewritten by the purchase script and the data rewritten by the transaction. commitScriptResultInUseDistributor This option is available when transactionUseDistributor is enabled. Processes rewritten by pre-scripts can also be included in the transaction for consumption and acquisition actions executed asynchronously. This allows transactions to run asynchronously while preventing only the script execution results from being reflected. acquireActionUseJobQueue An option available when enableAtomicCommit is enabled. It allows configuring the acquire action of the issued transaction to register a job with GS2-JobQueue, executing the acquire action asynchronously. This setting helps avoid issues when consume actions and acquire actions conflict, or when multiple configured acquire actions conflict with each other. distributorNamespaceId Configures the GS2-Distributor namespace used when automatically executing transactions. queueNamespaceId Configures the GS2-JobQueue namespace used when executing transaction acquisition actions via the job queue. Flowchart for determining which transaction system to use graph TD Start --\u003e 1st[\"enableAutoRun = true, enableAtomicCommit = true\"] 1st --\u003e Async{\"Does the game need to use the transaction result?\"} Async -- Need to wait --\u003e UseDistributor2[\"transactionUseDistributor = true\"] Async -- Waiting required --\u003e Conflict{\"Does a conflict error occur?\"} Conflict -- Not conflict --\u003e End Conflict -- Conflicted --\u003e 2nd{\"Investigate conflict details\"} 2nd -- Conflict is between script and transaction --\u003e UseDistributor[\"transactionUseDistributor = true\"] 2nd -- Transaction consumption actions --\u003e NotAtomicCommit[\"enableAtomicCommit = false\"] 2nd -- Transaction consumption action and acquisition action --\u003e UseJobQueue[\"acquireActionUseJobQueue = true\"] 2nd -- Transaction acquisition actions --\u003e UseJobQueue UseDistributor2 --\u003e 3rd{\"Is a pre-script configured?\"} 3rd -- Not configured --\u003e Conflict 3rd -- Configured --\u003e UseScript{\"Should the script result also be committed with the transaction?\"} UseScript -- Not required --\u003e Conflict UseScript -- Required --\u003e CommitScriptResultInUseDistributor[\"commitScriptResultInUseDistributor = true\"] CommitScriptResultInUseDistributor --\u003e Conflict NotAtomicCommit --\u003e End UseJobQueue --\u003e End","lang":"en","section":"articles","summary":"Design Principles for Transaction Settings in Game Server Services","title":"Transaction Settings","url":"/articles/tech/transaction/"},{"content":"","lang":"en","section":"get_start","summary":"Let's implement creating an account and logging in with Game Server Services.","title":"Tutorial","url":"/get_start/tutorial/"},{"content":"Amazon EventBridge is one of the features provided by AWS. By using this feature, you can connect to components such as Lambda/SQS on AWS to perform additional processing triggered by events that occur in GS2. How to use Activate Amazon EventBridge on GS2 First, access the AWS management console and open Amazon EventBridge. At this time, make sure to use us-east-1 (N.Verginia) as the region. Select Partner event sources from the side menu. Enter keywords in the search box to find Game Server Services. Select Set up and you will see a simple setup process. Press the “Copy” button next to Your AWS account ID to save the account ID. Go to GS2’s Management Console and select Project \u003e Update Settings from the side menu. Enable\" AWS EventBridge and enter the information you just copied in the ID of the AWS account to be used for notifications. Set the AWS region for notifications to us-east-1. This completes the configuration of EventBridge on GS2. Configure EventBridge to handle events received from GS2 on AWS The list of event sources related to GS2 created in the Partner event sources page of Amazon EventBridge has increased. Open the event source details and click the button “Associate with event bus”. Read the description and execute Associate. When the status becomes Active, it is ready to be used. Define event rules Select Rules from the side menu. A list of rules will be displayed, so select Create rule. Select “Create rule”. img_11.png Select the event source you just Associated for the Event bus and select Next. Next, write the settings to filter the events received from GS2. For details, please refer to the Amazon EventBridge documentation. This time, select All events to use all events in subsequent processing. Next, configure how the received events will be used. In this case, we will use AWS Lambda, so we will set the function we want to execute in Function. Send the events you want to subscribe to to EventBridge Create a namespace setting specifying EventBridge as the destination for completion notifications. Confirmation of operation Set up a simple function registered with AWS Lambda that simply prints the received event. In this case, since we have set up the linkage to EventBridge at the time of account registration, we register the account from the management console. If you check the execution log, you will see that the function is called. Checking the details of the log, we can see that information about the registered account and the namespace used to create the account are passed along. You can then rewrite the function to be registered with AWS Lambda and add any additional processing you wish. In this case, we used Python code, but AWS Lambda supports a variety of other programming languages. GS2 also provides SDKs for various programming languages, so it is possible to call GS2 functions from AWS Lambda.","lang":"en","section":"overview","summary":"Using Amazon Event Bridge Extending GS2 functionality with Amazon Event Bridge.\n","title":"Using Amazon Event Bridge","url":"/overview/workflow/coding/extend/event_bridge/"},{"content":"Extension methods available in GS2-Script extension scripts (Lua language). The Lua standard library is restricted inside the GS2-Script sandbox. Functions that load external resources or that catch errors internally — such as load , require , dofile , and pcall — are not available. The os library is also restricted for safety; only os.time() can be used. The table , string , and math libraries are available almost as-is. util.table_to_json Convert a Lua table type (array) to a JSON format string. Request Argument name Type Description table table Lua table Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result string JSON string of the conversion result Sample Code result = util.table_to_json({a=\"a\", b=1, c=false}) if result.isError then fail(result['statusCode'], result['errorMessage']) end json_str = result[\"result\"] Output {\"a\":\"a\",\"b\":1,\"c\":false} util.json_to_table Converts a string in JSON format to a Lua table type (array). Request Argument name Type Description jsonText string string in JSON format disableNumberStringToNumber bool Do not convert to numeric type when a numeric value is stored in JSON as a string type (default: false) Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result table Lua table of conversion results Sample Code result = util.json_to_table(\"{\\\"a\\\": \\\"a\\\", \\\"b\\\": 1, \\\"c\\\": false}\") if result.isError then fail(result['statusCode'], result['errorMessage']) end json_table = result[\"result\"] util.split Split a string. Request Argument name Type Description value string original string sep string delimiter Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result table Lua table of split strings Sample Code result = util.split(\"a,b,c\", \",\") if result.isError then fail(result['statusCode'], result['errorMessage']) end split_table = result[\"result\"] print(split_table[1]) print(split_table[2]) print(split_table[3]) Output a b c http.get Issues HTTP GET requests. Request Argument name Type Description url string URL of the connection Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result string HTTP Response Body Sample Code result = http.get(\"https://example.com\") if result.isError then fail(result['statusCode'], result['errorMessage']) end get_result = result[\"result\"] http.post Issue an HTTP POST request. Request Argument name Type Description url string URL of the connection contentType string Content-Type of the HTTP header body string HTTP request message body Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result string HTTP Response Body Sample Code result = http.post(\"https://example.com\", \"application/json\", \"{\\\"a\\\": 1}\") if result.isError then fail(result['statusCode'], result['errorMessage']) end post_result = result[\"result\"] util.random Generate a random floating point number between 0 and 1. Request Argument name Type Description Result member name type description isError bool presence of error statusCode int status code errorMessage string error message result float generated random number Sample Code result = util.random() if result.isError then fail(result['statusCode'], result['errorMessage']) end random_value = result[\"result\"] util.uuid Generate strings based on UUIDv4 Request Argument name Type Description Result member name type description isError bool presence of error statusCode int status code errorMessage string error message result float generated random number Sample Code result = util.uuid() if result.isError then fail(result['statusCode'], result['errorMessage']) end random_value = result[\"result\"] util.shared_random Generates a deterministic random number based on a seed and a counter, designed for use cases such as drawing systems where the same random sequence must be reproducible. The sequence is preserved across automatic re-executions of a stamp sheet, so the same values are obtained even when a transaction is retried. A separate counter is maintained per category , allowing multiple independent random sequences to be used within the same script. Request Argument name Type Description category int Category number used to distinguish random sequences Result Member name Type Description isError bool presence of error statusCode int status code errorMessage string error message result float generated random number Sample Code result = util.shared_random(1) if result.isError then fail(result['statusCode'], result['errorMessage']) end shared_value = result[\"result\"] fail Aborts script execution as a failure and returns an error to the API that invoked the script. Use it in pre-/post-scripts to perform validation and return an error when conditions are not met. Request Argument name Type Description errorCode string Error code to return ( BadRequest / Unauthorized / NotFound / Conflict / ServiceUnavailable / BadGateway , etc. HTTP status codes such as 400 or 401 are also accepted) message string Error message If errorCode does not match any of the known values, the error is treated as InternalServerError . Sample if not_allowed then fail(\"BadRequest\", \"validation.error.notAllowed\") end print Outputs an arbitrary string to the log. When GS2-Log is enabled, the printed content can be confirmed from the access logs. Use it for debugging within scripts or to record execution paths. Request Argument name Type Description message string Message to log Sample print(\"invoked with userId=\" .. args.userId) os.time Returns the server time at the moment the script is executed as a Unix timestamp (in seconds). If you are using the GS2-Distributor time-offset feature, the returned time reflects that offset. Sample now = os.time() gs2 A client for calling GS2 microservice APIs directly from within a Lua script in GS2-Script. Pass the service name as the argument, then chain the API name and its arguments. If the invoked API issues a transaction, that transaction is returned together with the transaction of the API that originally launched the script. Sample Fetching an item from GS2-Inventory: result = gs2(\"inventory\").get_item_set_by_user_id({ namespaceName = \"namespace-0001\", userId = args.userId, inventoryName = \"inventory-0001\", itemName = \"item-0001\", }) if result.isError then fail(result['statusCode'], result['errorMessage']) end For the list of available service names and API names, see the API reference of each microservice.","lang":"en","section":"articles","summary":"Description of utility methods available in Lua scripts executed by GS2-Script\n","title":"Utility methods of GS2-Script","url":"/articles/script/"},{"content":"Game as a Service have been common in Japan for more than a decade, and have become common or are becoming common in the West over the past few years. In order to realize an operation-based game, it is essential to have a metagame that supports the main game over a long period of time, not to mention an interesting main game. In this section, we would like to help developers get one step closer to better game design by explaining the concept of metagames. Main Game The main game is the core play of the game. If it is a battle royale game, it is the part of the game where 100 people descend on a vast battlefield and fight to the last man, or If it is an RPG, the main game is the battle against enemies and the progression of the scenario. The problem is that it is nearly impossible to establish a long-term management type game with only this. There are games out there that captivate players for years just because of the fun of the main game, but such games are rare. Metagame The metagame is a game cycle that is designed to captivate players for a long period of time through the efforts of the developer, rather than leaving it up to such miracles. Few titles in the West engage in metagaming, while it is taken for granted in Asian games. Based on the premise of these regional differences, this article will explain what kind of metagame is offered in the Asian region and what experiences are behind it. Reasons for the existence of a metagame There are several reasons for providing a metagame, but the following points are particularly important Bridging the gap between the speed of game development and the speed of play Avoid player fatigue Bridging the gap between game development speed and play speed You have probably seen many times the reality that a game you have worked hard every day for several years to develop is cleared in about 10 hours by players. To realize a Game as a Service, this gap must be bridged. Because if you don’t bring some kind of change to the game every month, players will get bored. However, the rate of development obviously takes longer than the rate of consumption. If players would be satisfied with just playing the main game repeatedly and would play for several years, we would not have to think about this, but as already mentioned, the probability of producing such a game is really low. So we need a metagame as a game cycle that requires less developer man-hours and more player man-hours. Not tire players out Getting players to play a little bit every day is important for the longevity of the game. This is because once a player stops playing, the effort required to get him or her to play again is very high. If the game cycle is such that the main game requires at least 20 minutes of serious effort to play, it becomes progressively more difficult to get players to play every day. This is because players get tired. The metagame can carry the message, “Just start it up for 5 minutes every day!” This will help players to play the game for 5 minutes every day. This will allow players to start the game for 5 minutes every day, so that the game can smoothly announce updates and seasonal events, and then return to the main game. Metagame Definition Meta-games provide play experiences outside of the main game, such as “developing characters for use in the main game” or “exploring viewpoints in the main game’s vast field. Such play should be designed to be a very long game cycle that basically takes weeks or months from setting a goal to actually completing it. Not to be forgotten is to incorporate the metagame into the game as a design that fulfills the reason for its existence, which we have already explained. Metagame Origins Now, to understand the metagame cycle, it is necessary to understand the history of Japan, North America/Europe, and China/Korea, where each of the three regions has gone through different processes to form the game that is the standard today. graph TD PCGame[\"PC Game\"] subgraph \"North America/Europe\" PCGame --\u003e USAmusumentMachine[\"Amusement machine\"] USAmusumentMachine --\u003e USConsoleGame[\"Home Video Game\"] end subgraph \"Japan\" PCGame --\u003e JPAmusumentMachine[\"Game Center\"] JPAmusumentMachine --\u003e JPConsoleGame[\"Home video game\"] JPConsoleGame --\u003e JPSocialGame[\"Social Game\"] JPSocialGame --\u003e JPSmartPhoneGame[\"Smartphone Game\"] end subgraph \"China/Korea\" PCGame --\u003e ASIAPCMMORPG[\"PC MMO RPG\"] ASIAPCMMORPG --\u003e ASIASmartPhoneGame[\"Smartphone Game\"] end class JPSocialGame emphasis class ASIAPCMMORPG emphasis The diagram shows how the standard game in each region has been fostered. Among them, the areas indicated by the red boxes are those developed with Game as a Service in mind. In other words, there have long been opportunities to think about Game as a Service in Japan, China, Korea, and other Asian regions, and there is an accumulation of knowledge for this purpose. The game cycle called “metagame” has emerged as a product of this process. Monetization cultivated in Japanese social games Remember Facebook games? It is probably a thing of the past for many in the community, “Oh, there was such a thing. However, the impact of Facebook games on the gaming industry has been significant, especially in Japan. In Japan, Japanese social network services such as mixi / mobage / GREE have also been working on games in response to Facebook games. The growth of mobage and GREE has been particularly strong, and there was a time when Japanese TV was dominated by their commercials. The source of this growth was the seemingly reckless challenge of expanding the number of users through F2P and attracting players with the limited expressive power of cell phone browsers. However, surprisingly, even to me, who was working for Nintendo at the time, many of the players immersed themselves in social games. Needless to say, there was a power of meta-gaming here, although I did not understand it at the time. After maximizing engagement through the power of metagames, social games gradually began to focus on monetization. This is where “digital gacha” was born with Konami’s Dragon Collection. This was the moment when the game cycle was established, in which characters obtained through gacha were developed in the metagame and then used to conquer the main game. China’s confluence and the future of North America and Europe China is now the region with the most active publishers in the gaming market. Japanese-style smartphone games, which have gradually become richer and more expressive in line with the shift from browser-based social games to smartphones, have also challenged the North American and European markets on numerous occasions. However, in terms of graphical expression, these games have failed to catch the eye of discerning players of home video games, and have not been successful outside of Japan. In the meantime, Genshin-Impact, which was designed to combine China’s MMORPG strengths with Japanese-style gacha monetization and a peripheral metagame cycle, has become a worldwide hit (with sales of over 5 billion USD from 2020 to 2022). The future of the North American and European markets cannot be discussed without Genshin-Impact’s presence. For Japanese developers, the seamless game experience that Genshin-Impact has achieved, rather than the page transitions of the browser game era, which have not been abandoned, will be very helpful. For developers in North America/Europe, they will be able to learn how to integrate a metagame into a rich game experience, such as those already in development, to create a long-running game that will generate huge sales. 2023-02-11 Kazutomo Niwa","lang":"en","section":"design_knowledge","summary":"What is the metagame that supports an operational game that provides player satisfaction for years to come?","title":"What is the metagame that supports Game as a Service?","url":"/design_knowledge/what_the_metagame/"},{"content":"Once you have created an account, create a project. A project can have a fee plan and a billing address. This means that you can set up different billing addresses for different projects, even within a single account. This should be a useful structure for developers who have publishers who pay GS2 usage fees. Once you have finished creating your project, you are ready to start using GS2.","lang":"en","section":"overview","summary":"How to create a project in GS2\n","title":"Create a project in GS2","url":"/overview/workflow/setup_gs2/create_project/"},{"content":"This section describes the flow of development using Game Server Services and the features that can be utilized at any given time. graph TD ProjectPlanning[\"Project Planning\"] --\u003e ArchitectGs2 subgraph Design ArchitectGs2[\"Consider how GS2 can be used in your project\"] end subgraph Start using GS2 ArchitectGs2 --\u003e HasGS2Account HasGS2Account{\"Already have a GS2 account\"} -- NO --\u003e RegistrationAccount[\"Create a GS2 account\"] --\u003e CreateGS2Project HasGS2Account -- YES --\u003e CreateGS2Project[\"Create a project in GS2\"] end subgraph Create resources in GS2 CreateGS2Project --\u003e CreateResource CreateResource[\"Create resources in GS2\"] end subgraph Implementation CreateResource --\u003e CodingGame CodingGame[\"Developing Game\"] end subgraph Verification CodingGame --\u003e QA QA[\"QA\"] end subgraph Release QA --\u003e Launch Launch[\"Service Launch\"] end subgraph Analysis Launch --\u003e AnalyticsGame AnalyticsGame[\"Analyze player behavior\"] end AnalyticsGame --\u003e CreateResource","lang":"en","section":"overview","summary":"Game Development Flow Using Game Server Services\n","title":"Development Flow","url":"/overview/workflow/"},{"content":"Models EzAccount Game Player Account An entity of identity information that identifies a game player. Game player accounts are anonymous accounts and consist of a user ID (UUID) and password (a random 32-character string), so game players do not need to enter their email address or other information. The issued Game Player Account is stored in the device’s local storage and is used for future logins.  userId string  UUID ~ 128 chars User ID password string  ~ 128 chars Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzTakeOver TakeOver Information TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.  userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzPlatformId Platform ID Holds IDs for various platforms such as X, Instagram, and Facebook. Other players can search for players using various platform IDs. When importing Instagram followers or Facebook friends as in-game friends, it is used to identify the GS2-Account account.  type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzPlatformUser Various platform user information Holds user information from external platforms. Contains the mapping between a platform-specific user identifier and the corresponding GS2-Account user ID, used for searching players by their platform identity.  type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform user is linked to. Used to map between external platform identities and GS2 anonymous accounts. EzBanStatus Account Ban Status Represents information about the BAN (access restriction) status applied to a Game Player Account. This type includes detailed information such as the reason for the BAN, the name of the BAN, and the scheduled date and time for the BAN to be lifted. Ban status can be applied to an account for various reasons, such as cheating or violation of the terms of service, and this type helps to manage that status. The system uses this information to control the account’s access permissions and to restrict or release access as necessary.  name string  UUID ~ 36 chars Ban status name Maintains a unique name for each Ban status. The name can be set to any value. If omitted, it is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Ban status. This ID allows for easy tracking of multiple Ban statuses. reason string  ~ 256 chars Reason for BAN Explains the specific reason for the BAN. It can be up to 256 characters long and helps to clarify the cause of the BAN. This information is not only referenced by the account administrator and the operations team, but also included in the response value to the game client. releaseTimestamp long  Date and time when the BAN will be released Indicates the date and time when the Account Ban will be released. Once this date and time has passed, the account will be automatically released from the BAN and normal access will be possible. Methods authentication Log in to an account Authenticate a game player using the user ID and password obtained at account creation. On successful login, account credentials and a signature are issued. Pass these to GS2-Auth::Login to obtain an access token for using GS2 services. Typically, you can use GS2-Profile::Login to combine this step with GS2-Auth::Login in a single call. See the sample programs in “Getting Started” for details. The account credentials and signature expire after 1 hour. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN password string  ~ 128 chars Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account. Result Type Description item EzAccount Game Player Account banStatuses List Ban status list body string Account information for signing subject signature string signature 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 PasswordIncorrectException UnauthorizedException Incorrect password specified. BannedInfinityException UnauthorizedException Account has been suspended. Implementation Example create Create a new game player account Call this when the game is launched for the first time to create a player account. On success, a user ID and password are returned. Save these two values to persistent storage (e.g., PlayerPrefs or local save data) for future logins. The password is automatically generated as a random value and cannot be set by the player. If you want players to transfer their account using a familiar identifier (such as an email address or social media account), register TakeOver Information separately. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzAccount Game player Account created Implementation Example addTakeOverSetting Register TakeOver Information Set up account recovery so that the player can restore their account after changing devices or reinstalling the app. By registering a takeover user ID (such as an email address) and a takeover password , the player can transfer their account to another device by entering the same combination. Multiple takeover methods can be set up for a single account. By using different slot numbers , you can store different types of credentials — for example, an email address in slot 0 and a social media account in slot 1. Slot numbers can be specified in the range of 0 to 1024. Note: This feature only stores data. Authentication with social accounts (OAuth, etc.) must be implemented separately on the game side. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item EzTakeOver TakeOver Information created Implementation Example addTakeOverSettingOpenIdConnect Register TakeOver Information using OpenID Connect Register TakeOver Information using authentication results from external login services such as Google or Apple (OpenID Connect). With this method, no password setup is required. To use this feature, you must configure the association between slot numbers and authentication services in the master data beforehand. Once OpenID Connect is configured for a slot, the standard “user ID + password” takeover method cannot be used for that slot. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. idToken string  ~ 10240 chars OpenID Connect ID Token Result Type Description item EzTakeOver TakeOver Information created Implementation Example deleteTakeOverSetting Delete TakeOver Information Deletes a registered TakeOver Information. After deletion, the account can no longer be recovered using this TakeOver Information. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description item EzTakeOver TakeOver Information deleted Implementation Example doTakeOver Execute account takeover Transfer an account by entering the takeover user ID and takeover password . If the entered information matches, the linked account’s user ID and password are returned. Save the returned user ID and password to your game’s persistent storage for future logins. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item EzAccount Game Player Account 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 PasswordIncorrectException UnauthorizedException Incorrect password specified. Implementation Example doTakeOverOpenIdConnect Execute account takeover using OpenID Connect Transfer an account using authentication from login services such as Google or Apple (OpenID Connect). The user ID and password of the account linked to the authentication are returned. Save the returned user ID and password to your game’s persistent storage for future logins. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. idToken string  ~ 10240 chars OpenID Connect ID Token Result Type Description item EzAccount Game Player Account Implementation Example get Get TakeOver Information by type Retrieves a single TakeOver Information by specifying its slot number (type). Use this to check which takeover method has been configured. For security reasons, the takeover password is not included in the response. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description item EzTakeOver TakeOver Information Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getAuthorizationUrl Get the OpenID Connect authorization URL Retrieves the URL for redirecting the player to the authentication page of an external login service such as Google or Apple. By directing the player to this URL, you can initiate the registration of TakeOver Information or the execution of account takeover using OpenID Connect. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description authorizationUrl string Authorization URL Implementation Example listTakeOverSettings Get a list of registered TakeOver Information Retrieves the list of TakeOver Information registered for this player. For security reasons, takeover passwords are not included in the response. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of TakeOver Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. updateTakeOverSetting Change the TakeOver password Change the password for the TakeOver Information. To make the change, the current (old) password must be provided. Note: If you want to enforce secure password changes using this API, make sure to disable access to the “delete TakeOver Information” API. Since deleting does not require password verification, a player could effectively change their password by deleting and re-creating the TakeOver Information. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. oldPassword string  ~ 128 chars Old Password password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item EzTakeOver TakeOver Information 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 PasswordIncorrectException UnauthorizedException Incorrect password specified. Implementation Example addPlatformIdSetting Register a Platform ID Saves a user ID from an external service such as X (formerly Twitter), Instagram, or Facebook, linked to the game account. Specify a type (slot number) in the range of 0 to 1024 to distinguish between platform types. Specify the userIdentifier as the user ID on each platform. Other players can search for a player by specifying the type and user identifier. For example, this can be used to implement a feature that adds social media friends as in-game friends. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. Result Type Description item EzPlatformId Platform ID created Implementation Example deletePlatformIdSetting Delete a Platform ID Deletes a registered Platform ID. After deletion, the player can no longer be found by searching with that Platform ID. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. Result Type Description item EzPlatformId Platform ID deleted Implementation Example findPlatformUser Search for a player by Platform ID Search for a game player by specifying the platform type and user identifier. For example, this can be used to find in-game players from a social media friends list. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. Result Type Description item EzPlatformUser Various platform user information Implementation Example getPlatformId Get a Platform ID by type Retrieves a single Platform ID by specifying its slot number (type). Use this to check which user ID is linked to a specific platform. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. Result Type Description item EzPlatformId Platform ID Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listPlatformIdSettings Get a list of registered Platform IDs Retrieves the list of external service IDs linked to this player. Use this to check which platform IDs have been registered. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Platform IDs nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Account SDK for Game Engine\n","title":"GS2-Account SDK for Game Engine API Reference","url":"/api_reference/account/game_engine/"},{"content":"Models EzPoint Ad Viewing Points Records the total number of points earned by the player by viewing ads. Each time a player views an ad, they earn points, which can be used to exchange rewards or purchase in-game benefits.  point long 0 0 ~ 9223372036854775805 Number of points held Indicates the number of points held by the user. This value increases as the user views ads and decreases as they exchange rewards and benefits. Methods getPoint Get the current ad reward points Retrieves the number of points the player has earned by watching rewarded ads (AdMob, Unity Ads, AppLovin MAX, etc.). Use this to display the player’s current point balance on the UI or to check if enough points are available before spending them. If no point record exists yet, a record with 0 points is automatically created and returned. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzPoint Ad Viewing Points Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnChangePointNotification Push notification when point changes due to ad viewing Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-AdReward SDK for Game Engine\n","title":"GS2-AdReward SDK for Game Engine API Reference","url":"/api_reference/ad_reward/game_engine/"},{"content":"Models EzAccessToken Access token A model that manages access tokens issued after user authentication. Access tokens are used to identify a session while a user is logged in to the service. Tokens have an expiration time, and when they expire, re-authentication is required.  token string  ~ 1024 chars Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. userId string  ~ 128 chars User ID expire long The absolute time 1 hour after the current time Expiration time A timestamp indicating the expiration time of the token. When this date is reached, the token becomes invalid. Unix time, milliseconds Methods login Log in to GS2 using account credentials Pass the body and signature obtained from GS2-Account::Authentication to log in and receive an access token . The access token is a temporary login credential valid for 1 hour, and is required to use GS2 services as a specific player. In most cases, you do not need to call this API directly. The Unity and Unreal Engine 5 SDKs provide Profile::Login, which combines GS2-Account::Authentication and this API into a single call. See Initialization / Game Engine for details. Request  keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN body string  ~ 524288 chars Signed authentication payload signature string  ~ 1024 chars Signature Result Type Description token string Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. 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 Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Auth SDK for Game Engine\n","title":"GS2-Auth SDK for Game Engine API Reference","url":"/api_reference/auth/game_engine/"},{"content":"Models EzBuffEntryModel Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period.  name string  ~ 128 chars Buff Entry Model name Buff Entry 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. targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel EzBuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction EzBuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Add to adjustment rate “mul” Multiply the adjustment rate by the specified value “value_add” Directly add values (only numerical values for models or actions) applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active. EzBuffTargetModel Buff Target Model Defines the target GS2 resource model and field for buff application. Specifies which model’s field value should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetModelName string (enum) enum { }  Model type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric field on the target model whose value will be modified by the buff. For example, a field representing experience points, attack power, or other numerical attributes. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Adjustment rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the field value after rate calculations. EzBuffTargetAction Buff Target Action Defines the target GS2 action and parameter for buff application. Specifies which action’s parameter should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetActionName string (enum) enum { \"Gs2Experience:AddExperienceByUserId\" , \"Gs2Experience:SubExperience\" , \"Gs2Experience:SubExperienceByUserId\" , \"Gs2Inventory:AcquireItemSetByUserId\" , \"Gs2Inventory:ConsumeItemSet\" , \"Gs2Inventory:ConsumeItemSetByUserId\" , \"Gs2Inventory:AcquireSimpleItemsByUserId\" , \"Gs2Inventory:ConsumeSimpleItems\" , \"Gs2Inventory:ConsumeSimpleItemsByUserId\" , \"Gs2Inventory:AcquireBigItemByUserId\" , \"Gs2Inventory:ConsumeBigItem\" , \"Gs2Inventory:ConsumeBigItemByUserId\" , \"Gs2Limit:CountUp\" , \"Gs2Limit:CountUpByUserId\" , \"Gs2Money:DepositByUserId\" , \"Gs2Money:Withdraw\" , \"Gs2Money:WithdrawByUserId\" , \"Gs2Money2:DepositByUserId\" , \"Gs2Money2:Withdraw\" , \"Gs2Money2:WithdrawByUserId\" , \"Gs2Stamina:ConsumeStamina\" , \"Gs2Stamina:ConsumeStaminaByUserId\" , \"Gs2Stamina:RecoverStaminaByUserId\" , }  Action type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric parameter on the target action whose value will be modified by the buff. For example, a parameter representing acquire count, consume amount, or reward quantity. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the parameter value after rate calculations. EzBuffTargetGrn GRN pattern that identifies the resources used as conditions for applying buffs Specifies a GRN template with placeholders to identify which resource instance the buff should be applied to. The model name identifies the GS2 service model, and the GRN pattern contains context variables (e.g., region, ownerId, namespaceName) that are resolved at runtime to match the target resource.  targetModelName string  ~ 64 chars Buff application condition model name The name of the GS2 service model used to resolve the condition GRN. This identifies which service’s resource model the GRN pattern refers to. targetGrn string  ~ 1024 chars Buff application condition GRN A GRN template with context placeholders (e.g., {region}, {ownerId}) that is resolved at runtime to identify the specific resource instance targeted by the buff. Methods getBuffEntryModel Get a buff definition by name Retrieves a single buff entry model by specifying its name. The returned information includes the application method (Rate Add / Mul / Value Add), what the buff targets, its priority, and the linked event period if configured. Use this to display the details of a specific buff, such as its effect description or active period. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). buffEntryName string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzBuffEntryModel Buff Entry Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBuffEntryModels Get a list of buff definitions Retrieves all buff entry models registered in this namespace. Each buff entry model defines a single buff effect — what it targets (e.g., a stat on a model or an action parameter), how it is applied (Rate Add / Mul / Value Add), its priority, and optionally an event period during which it is active. Use this to display available buffs in the game UI or to check which buffs are currently configured. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Buff Entry Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. applyBuff Apply buffs to the current player Evaluates all buff entries registered in this namespace and applies the matching ones to the player. For example, you can set up buffs such as “double EXP gain during an event” or “+10% gold drop rate when a certain item is owned.” There are three application methods: Rate Add : Adds to the multiplier (e.g., base 1.0 + 0.2 = 1.2x) Mul : Multiplies the current multiplier (e.g., multiplier * 0.5) Value Add : Adds a flat value after all rate calculations Buffs linked to a GS2-Schedule event are only active during that event period. Multiple buffs are applied in priority order (lower number = higher priority). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of applied buffs newContextStack string Context stack after applying buff Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Buff SDK for Game Engine\n","title":"GS2-Buff SDK for Game Engine API Reference","url":"/api_reference/buff/game_engine/"},{"content":"Models EzRoom Room A room represents the scope within which chat messages can be delivered. GS2-Chat rooms do not have the concept of participation. Therefore, to receive messages, it is sufficient to know the room name, and there is no need to join the room or register as a member. If you wish to limit the number of game players who can view the messages in a room, there are two options. The first is to set a password for the room. Second, you can whitelist the room and limit the game players by setting their user IDs in the whitelist. Note that if you set a password, even the game administrator will not be able to retrieve messages without knowing the password. This is because this may fall under the secret of communication stipulated in the Constitution of Japan. If you subscribe to a room, you can receive GS2-Gateway push notifications when new messages are sent to the room. By using this notification function, you will be able to know if there are any new messages without polling the room.  name string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). EzMessage Message Messages are data posted to a room. It has a field called category, which allows classification of messages. For example, a category of 0 is interpreted as a normal text message, while a category of 1 can be processed as a stamp (sticker). Messages posted will be automatically deleted after the message retention period set in the Chat Namespace’s messageLifeTimeDays setting has elapsed.  name string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID category int 0 0 ~ 2147483645 Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. metadata string  ~ 1024 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzSubscribe Room Subscription By subscribing to a room, you will be instantly informed of new Messages for that room. When subscribing, you can specify the category of the message. This feature can be used to subscribe only to Messages that are of high importance to you.  userId string  ~ 128 chars User ID roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. EzCategoryModel Category Model Category Model defines the categories used to classify messages posted in chat rooms. Each category is identified by a numeric value, and you can configure whether posts using player access tokens are allowed or rejected per category. This enables use cases such as system-only announcement categories where only the server can post messages.  category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens EzNotificationType Notification Type Configuration of categories for receiving new message notifications  category int 0 0 ~ 2147483646 Categories for which you receive new message notifications The numeric category identifier to filter notifications. Only messages matching this category will trigger a push notification for the subscription. enableTransferMobilePushNotification bool false Whether to forward to mobile push notifications when offline When enabled, if the recipient device is offline at the time of notification, the notification is forwarded to the mobile push notification service. This allows players to be notified of new messages even when the game is not running. Methods createRoom Create a chat room Creates a new chat room where players can send and receive messages. The namespace settings must allow players to create rooms; otherwise this call will fail. You can optionally set a password on the room. If a password is set, it must be provided to post or read messages. You can also set a whitelist of user IDs to restrict who can access the room. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). Result Type Description item EzRoom Room created 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. Implementation Example deleteRoom Delete a chat room Deletes a chat room that the player has created. Only the player who created the room (the owner) can delete it. All messages in the room will also be removed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. Result Type Description item EzRoom Room deleted 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. Implementation Example getRoom Get chat room information Retrieves the information of a specified chat room, such as its metadata and creation date. This does not require a password, even if the room has one set. Use this to display room details (e.g., room name or topic) before the player enters the room. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRoom Room Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getMessage Get a specific message by name Retrieves a single message from a chat room by specifying its message name (ID). Use this to display the details of a specific message, such as when the player taps on a notification. If the room has a password, it must be provided. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. gameSession GameSession GameSession password string ~ 128 chars Password Result Type Description item EzMessage Message 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. PasswordRequiredException BadRequestException A password must be set to access the room. PasswordIncorrectException BadRequestException The password set for the room does not match the password specified. Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listLatestMessages Get the latest messages in a chat room Retrieves the most recent messages in a chat room, in reverse chronological order (newest first). Use this when you want to show the latest conversation when a player first opens the chat screen. If the room has a password, it must be provided. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession limit int 30 1 ~ 1000 Number of data items to retrieve password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. Result Type Description items List List of Message nextPageToken string Page token to retrieve the rest of the listing 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. PasswordRequiredException BadRequestException A password must be set to access the room. PasswordIncorrectException BadRequestException The password set for the room does not match the password specified. Implementation Example listMessages Get messages in a chat room (from a specific time) Retrieves messages posted at or after the specified startAt time, in chronological order (oldest first). Use this when you want to fetch messages since the player last checked, for example after reconnecting or opening the chat screen. Only messages within the retention period configured in the namespace settings can be retrieved. If the room has a password, it must be provided. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession startAt long The absolute time 1 hour prior to the current time Start time for message retrieval Unix time, milliseconds limit int 30 1 ~ 1000 Number of data items to retrieve password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. Result Type Description items List List of Message 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. PasswordRequiredException BadRequestException A password must be set to access the room. PasswordIncorrectException BadRequestException The password set for the room does not match the password specified. Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. post Post a message to a chat room Sends a message to the specified chat room. You can attach a category number to classify the message type (e.g., 0 for text, 1 for stamps/stickers). The message content is stored in metadata as a free-format string — you can use it for text, JSON, or any data your game needs. If the room has a password, it must be provided to post. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession category int 0 0 ~ 2147483645 Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. metadata string  ~ 1024 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. password string ~ 128 chars Password Result Type Description item EzMessage Posted message 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 NoAccessPrivilegesException BadRequestException The whitelist configured for the room does not contain any currently logged in user. PasswordRequiredException BadRequestException A password must be set to access the room. PasswordIncorrectException BadRequestException The password set for the room does not match the password specified. Implementation Example listSubscribeRooms Get a list of rooms the player is subscribed to Retrieves the list of chat rooms that the player has subscribed to for new-message notifications. Use this to show a “subscribed rooms” list in the chat UI, so the player can quickly jump to rooms they care about. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Room Subscriptions nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. subscribe Subscribe to a chat room Subscribes the player to a chat room so they receive notifications when new messages are posted. You can filter which messages trigger notifications by setting category conditions. For example, you could set it to “only notify for category 1 (stamps)” or “notify for all categories.” If the player is offline when a notification arrives, it can be forwarded as a mobile push notification (depending on namespace settings). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. gameSession GameSession  GameSession notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. Result Type Description item EzSubscribe Room Subscription Implementation Example unsubscribe Unsubscribe from a chat room Stops receiving new-message notifications for the specified chat room. Use this when the player no longer wants to follow a room, such as when they leave a group or turn off notifications from a settings screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. gameSession GameSession  GameSession Result Type Description item EzSubscribe Unsubscribed room subscription Implementation Example updateSubscribeSetting Update notification setting for a subscribed room Changes which message categories trigger notifications for a room the player is already subscribed to. For example, the player might initially subscribe to all categories, then later change it to “stamps only” from a settings screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. gameSession GameSession  GameSession notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. Result Type Description item EzSubscribe Renewed Subscriptions Implementation Example getCategoryModel Get a message category definition by number Retrieves a single message category definition by specifying its category number. The returned information includes whether players are restricted from posting to this category (useful for categories reserved for server-side system messages). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. Result Type Description item EzCategoryModel Category Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCategoryModels Get a list of message category definitions Retrieves all message category definitions registered in this namespace. Categories let you classify messages by type — for example, category 0 for normal text and category 1 for stamps/stickers. You can also control posting permissions per category (e.g., allow only the server to post system announcements). Use this to build a category selector or to check available message types in the chat UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnPostNotification Push notification sent when a new message is posted to a subscribed room Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID category int Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. createdAt long Creation Timestamp Unix time, milliseconds * Set automatically by the server Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Chat SDK for Game Engine\n","title":"GS2-Chat SDK for Game Engine API Reference","url":"/api_reference/chat/game_engine/"},{"content":"Models EzDataObject Data Object Data objects are data uploaded by game players. Data is generation managed, with 30 days of historical data stored. Access permissions can be set for the data. There are three types of scopes: public : Accessible to anyone protected : Accessible only to game players with specified user IDs private : Accessible only to yourself  dataObjectId string * ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. userId string  ~ 128 chars User ID scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” * [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” status string (enum) enum {   “ACTIVE”,   “UPLOADING”,   “DELETED” }  Status The current lifecycle state of the data object. ACTIVE indicates the data is available for access, UPLOADING indicates a new version is being uploaded, and DELETED indicates the object has been marked for deletion (actual removal occurs 30 days later). Definition Description “ACTIVE” Active “UPLOADING” Uploading “DELETED” Deleted (Actual deletion 30 days after the deletion process) generation string ~ 128 chars Data Generation An identifier representing the current version of the uploaded data. Each time data is re-uploaded, a new generation ID is assigned. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzDataObjectHistory Data Object History You can check the update history of Data Objects. Each time a data object is re-uploaded, a history record is created containing the generation ID and file size. Historical data is retained for 30 days, allowing rollback and audit of previous versions.  dataObjectHistoryId string * ~ 1024 chars Data Object History A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server generation string  ~ 128 chars Generation ID A unique identifier for the specific version of the data object at the time of upload. Corresponds to the generation field in the DataObject and can be used with PrepareDownloadByGeneration to download this specific version. contentLength long  0 ~ 10485760 File size The size of the uploaded data in bytes for this generation. Maximum file size is 10 MB (10,485,760 bytes). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Methods deleteDataObject Delete an uploaded file Marks the specified data object for deletion. The actual file is removed after 30 days. Use this when the player wants to delete save data or other uploaded content they no longer need. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. Result Type Description item EzDataObject Data object 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 InvalidStatusException BadRequestException DataObject is not in operable state. Implementation Example doneUpload Finalize a file upload Call this after you have finished uploading the file to the URL returned by PrepareUpload or PrepareReUpload. This confirms the upload and makes the data object available for download (status changes to ACTIVE ). If you skip this step, the data object remains in UPLOADING status and cannot be downloaded. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. Result Type Description item EzDataObject Data object 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 InvalidStatusException BadRequestException DataObject is not in operable state. NotUploadedException BadRequestException DataObject is not uploaded. Implementation Example listMyDataObjects Get a list of the player’s uploaded data Retrieves a list of data objects (files) that the player has uploaded. You can filter by status: ACTIVE (available for download), UPLOADING (upload in progress), or DELETED (scheduled for deletion). Use this to show a save-data list screen or to check what files the player currently has stored. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession status Status Definition Description “ACTIVE” Active “UPLOADING” Uploading “DELETED” Deleted(Actual deletion 30 days after the deletion process) 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 List of Data object nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. prepareDownload Get a download URL for a file (by data object ID) Returns a temporary download URL for the specified data object. The data object is identified by its ID (GRN). Access control is applied — only the file owner or users in the allow-list can download. Use the returned URL to download the file with an HTTP GET request. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN gameSession GameSession  GameSession Result Type Description item EzDataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByUserIdAndDataObjectName Get a download URL for another player’s file (by user ID and name) Downloads another player’s data by specifying their user ID and the data object name. Access control is applied — the data must be public , or the requesting player must be in the owner’s allow-list. Use this when players share data with each other, such as custom levels or replays. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. Result Type Description item EzDataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadOwnData Get a download URL for the player’s own file (by name) A convenient way to download the player’s own data by specifying the data object name instead of its ID. Use this when the player wants to load their own save data or uploaded content. Returns a temporary download URL and the file size. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. gameSession GameSession  GameSession Result Type Description item EzDataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example Download Download Data Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name Result Type Description item byte array binary data Implementation Example DownloadByUserIdAndDataObjectName Download data by specifying user ID and data name Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name Result Type Description item byte array binary data Implementation Example DownloadOwn Download own data Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name Result Type Description item byte array binary data Implementation Example ReUpload Re-upload Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name data byte array binary data Result Type Description item EzDataObject Data object uploadUrl string URL used to execute the upload process Implementation Example prepareReUpload Prepare to re-upload (overwrite) an existing file Returns a new upload URL for replacing the content of an existing data object. The previous version of the file is kept in the history, so you can still download older versions by generation number. After uploading the new file to the returned URL, call DoneUpload to finalize it. Re-upload flow: PrepareReUpload → PUT file to returned URL → DoneUpload Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data to be uploaded Result Type Description item EzDataObject Data object uploadUrl string URL used to execute the upload process Implementation Example prepareUpload Prepare to upload a new file Creates a new data object and returns an upload URL. After calling this API, upload the file to the returned URL using an HTTP PUT request, then call DoneUpload to finalize it. You can set the access scope ( public or protected ) and specify which users are allowed to download the file. If updateIfExists is true, uploading a file with the same name will update the existing one instead of returning an error. Upload flow: PrepareUpload → PUT file to returned URL → DoneUpload Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession name string ~ 128 chars Data Object Name If not specified, a UUID is automatically assigned. scope “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data to be uploaded allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” updateIfExists bool false Whether to raise an error if data already exists or to update the data Result Type Description item EzDataObject Data object uploadUrl string URL used to execute the upload process Implementation Example restoreDataObject Repair a data object’s management information Fixes inconsistencies between a data object’s metadata and its actual file. If the recorded file size or version number does not match the real file (e.g., due to an interrupted upload), this API corrects the metadata. You normally do not need to call this — it is only needed for recovery when something goes wrong during an upload. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzDataObject Data object 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 InvalidStatusException BadRequestException DataObject is not in operable state. Implementation Example updateDataObject Update access settings of a data object Changes who can access an uploaded data object. You can switch the scope between public (anyone can download) and protected (only specified users can download), and update the list of allowed user IDs. This does not change the file content itself — to update the file, use PrepareReUpload instead. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession scope “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” Result Type Description item EzDataObject Data object Implementation Example listDataObjectHistories Get the version history of a data object Retrieves the list of past versions (generations) of a data object. Every time you re-upload a file with PrepareReUpload, the previous version is saved in the history. Each entry shows the file size and when it was created, so you can check what changed and when. Use this to build a version history screen or to let the player revert to an older save. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. 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 List of Data Object Histories nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Datastore SDK for Game Engine\n","title":"GS2-Datastore SDK for Game Engine API Reference","url":"/api_reference/datastore/game_engine/"},{"content":"Models EzEntry Entry acquired by game player Represents a single dictionary entry that a game player has collected. Each entry corresponds to an EntryModel and records the acquisition timestamp. The possession state is binary—either the entry exists (collected) or it does not—with no concept of quantity.  entryId string * ~ 1024 chars Entry A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string ~ 128 chars User ID name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). acquiredAt long * Current time Date of acquisition The timestamp when this entry was first collected by the game player. Automatically set to the current time at the moment of registration and cannot be modified afterwards. EzLike Entry registered as a favorite Represents a dictionary entry that a game player has marked as a favorite (liked). Allows players to bookmark specific entries in the dictionary for quick access. Each like references an EntryModel by name and is unique per user—the same entry cannot be liked twice.  likeId string * ~ 1024 chars Like Entry A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string ~ 128 chars User ID name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). EzEntryModel Entry Model An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model.  name string  ~ 128 chars Entry Model name 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. EzConfig Configuration A key-value pair applied to transaction variables during distributed transaction execution. Allows dynamic substitution of placeholder values in transaction parameters at runtime.  key string  ~ 64 chars Name The variable name used as the placeholder key in transaction parameters. Must match the placeholder defined in the transaction template. value string ~ 51200 chars Value The value to substitute for the placeholder key at transaction execution time. This value replaces the corresponding placeholder in the transaction parameters. Methods getEntryModel Get a collectible item definition by name Retrieves a single entry model by specifying its name. Use this to display the details of a specific collectible item, such as its description or metadata, when the player taps on an entry in the collection screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). entryName string  ~ 128 chars Entry Model name Result Type Description item EzEntryModel Entry Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listEntryModels Get a list of collectible item definitions Retrieves all entry models (collectible item types) registered in this namespace. Entry models define the items that can appear in the player’s collection — for example, monsters in a bestiary, characters in an album, or achievements. Use this to display the full list of collectible items on a collection/encyclopedia screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Entry Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getEntry Check if the player has collected a specific entry Checks whether the player has obtained a specific collectible item by specifying the entry model name. Use this to show a “collected” or “not yet collected” status on the detail screen of a collection item. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzEntry Entry Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getEntryWithSignature Get an entry with a tamper-proof signature Retrieves an entry along with a cryptographic signature that proves the data has not been tampered with. This is useful when you need to verify on an external server that the player really owns a specific collection entry — for example, to grant rewards based on collection progress through a custom server. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzEntry Entry body string Entry information for signature subject signature string signature Implementation Example listEntries Get a list of the player’s collected entries Retrieves the list of entries (collectible items) that the player has obtained so far. Use this to build a collection/encyclopedia screen showing which items the player has unlocked. By comparing this list with the full entry model list, you can show collected vs. uncollected items. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession limit int 30 1 ~ 10000 Number of data items to retrieve pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of Entries nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. addLikes Add entries to favorites Marks one or more entries as favorites for the player. You can specify multiple entry names at once to batch-add favorites. If an entry is already in the favorites list, it is simply skipped (no error). Use this when the player taps a “favorite” button on the collection screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession entryModelNames List [] 0 ~ 100 items List of Entry Model names Result Type Description items List List of Added Likes Implementation Example deleteLikes Remove entries from favorites Removes one or more entries from the player’s favorites list. You can specify multiple entry names at once to batch-remove favorites. Use this when the player taps a “remove from favorites” button on the collection screen. The collection status of the entries is not affected — they remain collected. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession entryModelNames List [] 0 ~ 100 items List of Entry Model names Result Type Description items List List of Deleted Likes Implementation Example getLike Check if a specific entry is favorited Checks whether the player has marked a specific entry as a favorite. Use this to show a “favorited” icon or highlight on the detail screen of a collection item. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzLike Like Entry Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listLikes Get a list of the player’s favorite entries Retrieves the list of entries that the player has marked as favorites. Favorites are managed separately from collection — even if an entry is collected, it is not automatically favorited. Use this to display a “favorites” tab in the collection screen, letting the player quickly access the items they care about. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession limit int 30 1 ~ 1000 Number of data items to retrieve pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of Likes nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Dictionary SDK for Game Engine\n","title":"GS2-Dictionary SDK for Game Engine API Reference","url":"/api_reference/dictionary/game_engine/"},{"content":"Models EzStampSheetResult Transaction execution result (Legacy) Records the execution results of a transaction processed via server-side auto-execution. Contains the request payloads and response results for each phase: verify actions (precondition checks), consume actions (that deduct resources), and the acquire action (that grants resources). Also tracks HTTP status codes for error detection and retry logic.  transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. taskRequests List 0 ~ 100 items List of Consume Action request payload sheetRequest EzAcquireAction  Acquire Action request payload taskResults List [] 0 ~ 100 items Consume Action execution results sheetResult string ~ 1048576 chars Acquire Action execution results EzTransactionResult Transaction execution result Records the execution results of a distributed transaction processed via server-side auto-execution. Contains structured results for each phase: verify actions (precondition checks), consume actions (resource deductions), and acquire actions (resource grants). Each action result includes the request, HTTP status code, and response payload. Errors are detected by checking status codes (non-2xx), and retries are triggered for conflict (409) or server errors (5xx).  transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. verifyResults List 0 ~ 100 items List of verify action execution results consumeResults List 0 ~ 100 items List of Consume Action execution results acquireResults List 0 ~ 100 items List of acquire action execution results EzDistributorModel Distributor Model A Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages.  name string  ~ 128 chars Distributor Model name Distributor 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzDistributeResource Distribute Resource Represents a single resource distribution operation consisting of an acquire action and its request parameters. Used to specify which GS2 API action to execute and with what parameters when distributing resources to a player.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzBatchRequestPayload API Batch Request Represents a single API request within a batch execution. Multiple batch request payloads can be sent together to execute several GS2 API calls in a single round trip, reducing network overhead and latency.  requestId string  ~ 128 chars Request ID A client-assigned identifier for this request within the batch. Used to correlate each request with its corresponding result in the batch response. service string (enum) enum {   “account”,   “adReward”,   “auth”,   “buff”,   “chat”,   “datastore”,   “deploy”,   “dictionary”,   “distributor”,   “enchant”,   “enhance”,   “exchange”,   “experience”,   “formation”,   “friend”,   “gateway”,   “grade”,   “guard”,   “guild”,   “identifier”,   “idle”,   “inbox”,   “inventory”,   “jobQueue”,   “key”,   “limit”,   “lock”,   “log”,   “loginReward”,   “lottery”,   “matchmaking”,   “megaField”,   “mission”,   “money”,   “money2”,   “news”,   “quest”,   “ranking”,   “ranking2”,   “realtime”,   “schedule”,   “script”,   “seasonRating”,   “serialKey”,   “showcase”,   “skillTree”,   “stamina”,   “stateMachine”,   “version” }  Service The GS2 microservice name to call (e.g., “inventory”, “experience”, “money”). Determines which service endpoint receives this API request. Definition Description “account” GS2-Account “adReward” GS2-AdReward “auth” GS2-Auth “buff” GS2-Buff “chat” GS2-Chat “datastore” GS2-Datastore “deploy” GS2-Deploy “dictionary” GS2-Dictionary “distributor” GS2-Distributor “enchant” GS2-Enchant “enhance” GS2-Enhance “exchange” GS2-Exchange “experience” GS2-Experience “formation” GS2-Formation “friend” GS2-Friend “gateway” GS2-Gateway “grade” GS2-Grade “guard” GS2-Guard “guild” GS2-Guild “identifier” GS2-Identifier “idle” GS2-Idle “inbox” GS2-Inbox “inventory” GS2-Inventory “jobQueue” GS2-JobQueue “key” GS2-Key “limit” GS2-Limit “lock” GS2-Lock “log” GS2-Log “loginReward” GS2-LoginReward “lottery” GS2-Lottery “matchmaking” GS2-Matchmaking “megaField” GS2-MegaField “mission” GS2-Mission “money” GS2-Money “money2” GS2-Money2 “news” GS2-News “quest” GS2-Quest “ranking” GS2-Ranking “ranking2” GS2-Ranking2 “realtime” GS2-Realtime “schedule” GS2-Schedule “script” GS2-Script “seasonRating” GS2-SeasonRating “serialKey” GS2-SerialKey “showcase” GS2-Showcase “skillTree” GS2-SkillTree “stamina” GS2-Stamina “stateMachine” GS2-StateMachine “version” GS2-Version methodName string  ~ 128 chars Method Name The API method name to invoke on the target service (e.g., “describeNamespaces”, “getInventory”). Must match a valid API method for the specified service. parameter string  ~ 10240 chars Parameter The JSON-serialized request parameters for the API method. Must conform to the request schema of the specified service method. EzBatchResultPayload API Batch Result Represents the result of a single API request within a batch execution. Each result is correlated with its original request by the request ID and contains the HTTP status code and JSON response payload.  requestId string  ~ 128 chars Request ID The client-assigned identifier matching the corresponding batch request. Used to correlate this result with its original request. statusCode int  100 ~ 1000 Status Code The HTTP status code returned by the GS2 API for this batch request. 2xx indicates success, 4xx indicates a client error, and 5xx indicates a server error. resultPayload string  ~ 10240 chars Response The JSON response body returned by the GS2 API for this batch request. Contains the API method’s response data or error details. EzAcquireAction Acquire Action Represents a resource acquisition operation within a distributed transaction. Corresponds to an acquire action that grants resources (e.g., items, currency, experience) to the player. Contains the GS2 API action identifier and the JSON-serialized request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzConsumeAction Consume Action Represents a resource consumption operation within a distributed transaction. Corresponds to a consume action that deducts resources (e.g., items, currency, stamina) from the player. Consume actions are executed before the acquire action to ensure the player meets the required cost.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action Represents a precondition verification operation within a distributed transaction. Executed before consume and acquire actions to validate that conditions are met (e.g., checking inventory capacity, verifying quest completion status). If any verify action fails, the entire transaction is aborted.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireActionResult Acquire Action execution result Records the result of a single acquire action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.  acquireRequest string  ~ 524288 chars JSON string of the request used when executing the action statusCode int 0 ~ 999 Status code The HTTP status code returned by the GS2 API for this acquire action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. acquireResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the acquire action. Contains the details of the acquired resources and may include a chained transaction ID. EzConsumeActionResult Consume Action execution result Records the result of a single consume action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.  consumeRequest string  ~ 524288 chars JSON string of the request used when executing the action statusCode int 0 ~ 999 Status code The HTTP status code returned by the GS2 API for this consume action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. consumeResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the consume action. Contains the details of the consumed resources. EzVerifyActionResult Verify Action execution result Records the result of a single verify action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API.  verifyRequest string  ~ 524288 chars JSON string of the request used when executing the action statusCode int 0 ~ 999 Status code The HTTP status code returned by the GS2 API for this verify action. 2xx indicates the verification passed, and non-2xx indicates the precondition was not met. verifyResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the verify action. Contains the verification result details. Methods getDistributorModel Get a distributor model definition by name Retrieves a single distributor model by specifying its name. The returned information includes the allowed service actions and the inbox namespace configured for overflow handling. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzDistributorModel Distributor Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listDistributorModels Get a list of distributor model definitions Retrieves all distributor models registered in this namespace. A distributor model defines the rules for resource distribution, including which service actions are allowed and where to send overflow items when a player’s inventory is full (e.g., to the gift box / inbox). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Distributor Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. batchExecuteApi Execute multiple API calls in a single batch Sends multiple GS2 API requests in one call and receives all responses together. This reduces the number of round-trips and improves performance when you need to call several APIs at the same time — for example, fetching inventory, stamina, and quest progress all at once when a player opens the home screen. Request  requestPayloads List  1 ~ 100 items Batch request Result Type Description results List Batch result Implementation Example freezeMasterData Freeze master data at the current point in time Creates a snapshot of the current master data so that subsequent transactions use this fixed version, even if the master data is updated later. This is useful for ensuring consistency — for example, if a player starts a quest, the rewards should be based on the master data at the time they started, not when they finish. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example freezeMasterDataBySignedTimestamp Freeze master data at a specific signed timestamp Freezes master data at a specific point in time using a signed timestamp. Unlike FreezeMasterData (which uses “now”), this lets you specify an exact time — useful when the freeze point was determined earlier (e.g., on the server side). The signed timestamp can be issued with SignFreezeMasterDataTimestamp. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession body string  ~ 1024 chars Body signature string  ~ 256 chars Signature keyId string  ~ 1024 chars GS2-Key encryption key A unique resource name assigned to all information handled by GS2\" \u003e GRN used for signature calculation Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example runStampSheet Run an acquire action (give resources) Executes a single acquire action, which grants resources to the player as part of a transaction. For example, giving items, adding experience points, or awarding in-game currency. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description statusCode int Status code result string Response content Implementation Example runStampSheetExpress Execute all actions in a transaction at once (express mode) Runs all verify, consume, and acquire actions of a transaction in a single API call, which is faster than running them one by one. If an error occurs, call this API again — retrying is safe because the system prevents consume actions from being applied more than once. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description verifyTaskResultCodes List Verify Action execution status code verifyTaskResults List Verify Action execution results taskResultCodes List Consume Action execution status code taskResults List Consume Action execution results sheetResultCode int Acquire Action execution status code sheetResult string Acquire Action execution result response content Implementation Example runStampSheetExpressWithoutNamespace Execute all actions in a transaction at once without a namespace (express mode) Combines the speed of express mode with the lightweight approach of skipping the namespace. Runs all verify, consume, and acquire actions in a single call. Retrying is safe because duplicate consume actions are prevented. Trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description verifyTaskResultCodes List Verify Action execution status code verifyTaskResults List Verify Action execution results taskResultCodes List Consume Action execution status code taskResults List Consume Action execution results sheetResultCode int Acquire Action execution status code sheetResult string Acquire Action execution result response content Implementation Example runStampSheetWithoutNamespace Run an acquire action without specifying a namespace A lightweight variant of RunStampSheet that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description statusCode int Status code result string Response content Implementation Example runStampTask Run a consume action (spend resources) Executes a single consume action, which deducts resources from the player as part of a transaction. For example, spending in-game currency, consuming stamina, or using up an item. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). stampTask string  ~ 5242880 chars Consume Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runStampTaskWithoutNamespace Run a consume action without specifying a namespace A lightweight variant of RunStampTask that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  stampTask string  ~ 5242880 chars Consume Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runVerifyTask Run a verify action (check a precondition) Executes a single verify action, which checks whether a precondition is satisfied before a transaction proceeds. For example, verifying that a player owns a required item or has reached a certain level. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyTask string  ~ 5242880 chars Verify Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runVerifyTaskWithoutNamespace Run a verify action without specifying a namespace A lightweight variant of RunVerifyTask that skips the namespace specification. This reduces overhead but has trade-offs: transaction logs are not recorded in GS2-Log, and overflow handling is not available. You normally do not need to call this directly — the SDK handles it automatically when processing transactions. Request  verifyTask string  ~ 5242880 chars Verify Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN contextStack string ~ 32768 chars Context of request Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example setDefaultConfig Set default config values for transactions Prepares a context with default config values that will be used when issuing transactions. Config values act as variables that can be embedded in transaction actions — for example, specifying a slot name or a quantity. By setting defaults here, you do not need to pass them every time a transaction is issued. Request  gameSession GameSession  GameSession config List  1 ~ 1000 items Configuration values applied to transaction placeholders Result Type Description newContextStack string Context stack for applying the default configuration Implementation Example getStampSheetResult Get the result of a completed transaction (legacy) Retrieves the execution result of a previously completed transaction by specifying its transaction ID. The result includes the status and response of each action (verify, consume, acquire) that was executed. Use this to check what happened in a transaction — for example, to confirm what rewards were actually granted. This API retrieves results for legacy (stamp-sheet-based) transactions. For newer transaction types, use GetTransactionResult instead. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. Result Type Description item EzStampSheetResult Transaction execution result Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getTransactionResult Get the result of a completed transaction Retrieves the execution result of a previously completed transaction by specifying its transaction ID. The result includes the status and response of each action (verify, consume, acquire) that was executed. Use this to check what happened in a transaction — for example, to confirm what rewards were actually granted or what resources were consumed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. Result Type Description item EzTransactionResult Transaction execution result Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnAutoRunStampSheetNotification Push notification when transaction auto-execution is complete Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID transactionId string Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. Implementation Example OnAutoRunTransactionNotification Push notification when transaction auto-execution is complete Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID transactionId string Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Distributor SDK for Game Engine\n","title":"GS2-Distributor SDK for Game Engine API Reference","url":"/api_reference/distributor/game_engine/"},{"content":"Models EzBalanceParameterStatus Balance Parameter Status Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Balance Parameter Model and contains the concrete values assigned to each parameter slot after the drawing process.  parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List  1 ~ 10 items List of balance parameter values The concrete values assigned to each parameter slot after the drawing process. Each entry corresponds to a parameter slot defined in the model and contains the actual numeric value allocated. The sum of all values equals the total value specified in the model. EzRarityParameterStatus Rarity Parameter Status Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Rarity Parameter Model and contains the concrete values selected through weighted lottery for each granted parameter slot.  parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List 0 ~ 10 items List of rarity parameter values The concrete parameter values selected through weighted lottery for each granted slot. The number of entries is determined by the parameter count draw, and each entry’s value is selected from the value model pool. May contain fewer entries than the maximum parameter count. EzBalanceParameterModel Balance Parameter Model Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters.  name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. EzBalanceParameterValueModel Balance Parameter Value Model Defines a single parameter slot available within a balance parameter. Each entry specifies a named slot (e.g., ATK, DEF, SPD) that receives a portion of the total value during the drawing process.  name string  ~ 64 chars Name The identifier for this parameter slot (e.g., ATK, DEF, SPD). Must be unique within the balance parameter model. Used as the key when storing and retrieving drawn parameter values. metadata string ~ 512 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. EzRarityParameterModel Rarity Parameter Model Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions.  name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. EzRarityParameterCountModel Rarity Parameter Count Model Defines a single entry in the weighted lottery for determining how many parameter slots are granted to a resource. Each entry pairs a parameter count with a draw weight, allowing fine-grained control over the probability distribution of parameter quantities.  count int  0 ~ 10 Count The number of parameter slots to grant when this entry is drawn. For example, a count of 3 means the resource will receive 3 parameter values selected from the value model pool. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when determining the parameter count. Higher values increase the probability of this count being selected. The actual probability is this weight divided by the sum of all weights in the count model list. EzRarityParameterValueModel Rarity Parameter Value Model Defines a single entry in the weighted lottery pool for rarity parameter values. Each entry specifies a parameter name, game-defined resource details, and a draw weight that determines its selection probability relative to other entries in the pool.  name string  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. metadata string ~ 512 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. resourceName string  ~ 64 chars Parameter Resource Name for Game (Not used for GS2) A game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. resourceValue long  0 ~ 9223372036854775805 Parameter Resource Value for Game (Not used for GS2) A game-defined numeric value for this parameter (e.g., 50 for +50 attack power). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when selecting parameter values. Higher values increase the probability of this entry being selected. The actual probability is this weight divided by the sum of all weights in the pool. EzBalanceParameterValue Balance Parameter Value Represents the actual value assigned to a single parameter slot within a balance parameter status. Contains the slot name and its concrete numeric value after the drawing process.  name string  ~ 64 chars Name The name of the parameter slot (e.g., ATK, DEF, SPD). Corresponds to a parameter slot defined in the Balance Parameter Value Model. value long  0 ~ 9223372036854775805 Value The numeric value assigned to this parameter slot. Determined by the initial value strategy (average or lottery) when the balance parameter is first drawn. The sum of all slot values equals the total value defined in the model. EzRarityParameterValue Rarity Parameter Value Represents the actual value assigned to a single parameter slot within a rarity parameter status. Contains the slot name and the resource details (name and value) selected through weighted lottery from the value model pool.  name string  ~ 64 chars Name The name of the parameter value selected from the value model pool. Corresponds to the name defined in the Rarity Parameter Value Model entry that was drawn. resourceName string  ~ 64 chars Resource Name The game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). Copied from the drawn Rarity Parameter Value Model entry for use in game logic. resourceValue long  0 ~ 9223372036854775805 Resource Value The numeric value of the resource associated with this parameter. Copied from the drawn Rarity Parameter Value Model entry. Used by game logic to apply the parameter’s effect (e.g., +50 attack power). EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getBalanceParameterModel Get a balance parameter definition by name Retrieves a single balance parameter model by specifying its name. The returned information includes the total value to distribute, the list of parameter slots (e.g., ATK, DEF, SPD), and how the initial values are determined. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzBalanceParameterModel Balance Parameter Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBalanceParameterModels Get a list of balance parameter definitions Retrieves all balance parameter models registered in this namespace. A balance parameter distributes a fixed total value across multiple stats — for example, splitting 100 points among ATK, DEF, and SPD so the total always equals 100. Use this to display available parameter types or to check the configuration of parameter models on a weapon/equipment detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Balance Parameter Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getBalanceParameterStatus Get the balance parameter values of a specific item Retrieves the current balance parameter values for a specific item (property) owned by the player. The values were randomly determined when the item was created (or last re-rolled), and the sum of all values always equals the model’s total value. Use this to display the individual stat breakdown (e.g., ATK: 40, DEF: 35, SPD: 25) on an item detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. Result Type Description item EzBalanceParameterStatus Balance Parameter Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBalanceParameterStatuses Get a list of the player’s balance parameter values Retrieves the current balance parameter values assigned to the player’s items. You can filter by parameter name to see values for a specific parameter type only. For example, this returns the ATK/DEF/SPD distribution for each weapon the player owns. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. gameSession GameSession  GameSession 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 List of Balance Parameter Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRarityParameterModel Get a rarity parameter definition by name Retrieves a single rarity parameter model by specifying its name. The returned information includes the maximum number of parameter slots, how the slot count is determined, and the list of possible values with their rarity weights (drop rates). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzRarityParameterModel Rarity Parameter Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRarityParameterModels Get a list of rarity parameter definitions Retrieves all rarity parameter models registered in this namespace. A rarity parameter randomly assigns values to parameter slots based on rarity-weighted probabilities — for example, a weapon might get skill slots filled with Common, Rare, or Legendary abilities. Use this to display available parameter types or to check the rarity configuration on an equipment screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Rarity Parameter Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRarityParameterStatus Get the rarity parameter values of a specific item Retrieves the current rarity parameter values for a specific item (property) owned by the player. The values were randomly drawn based on the rarity weights defined in the model when the item was created (or last re-rolled). Use this to display the skills or abilities attached to a weapon or equipment on a detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. Result Type Description item EzRarityParameterStatus Rarity Parameter Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRarityParameterStatuses Get a list of the player’s rarity parameter values Retrieves the current rarity parameter values assigned to the player’s items. You can filter by parameter name to see values for a specific parameter type only. For example, this returns which skill slots (Common, Rare, Legendary) each of the player’s weapons has. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. gameSession GameSession  GameSession 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 List of Rarity Parameter Models nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. verifyRarityParameterStatus Verify the rarity parameters of a specific item Checks whether a specific item’s rarity parameters meet a given condition. Three check types are available: have : the item has a specific parameter value (e.g., has the “Fire Slash” skill) havent : the item does not have a specific parameter value count : the item has a specific number of parameter slots filled Use this as a precondition — for example, requiring a weapon to have a certain skill before allowing an upgrade. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. verifyType  Type of verification Definition Description “havent” The specified parameter must not be held “have” The specified parameter must be held “count” The number of parameters held must be the specified number parameterValueName string {verifyType} in [“havent”, “have”]  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. parameterCount int {verifyType} in [“count”]  0 ~ 10 Number of parameters to verify Result Type Description item EzRarityParameterStatus Rarity Parameter Status Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Enchant SDK for Game Engine\n","title":"GS2-Enchant SDK for Game Engine API Reference","url":"/api_reference/enchant/game_engine/"},{"content":"Models EzProgress Enhance Progress It is created at the beginning of the enhance and deleted at the end. When you exit the application in the middle of an enhance, this data will remain. It is possible to resume the game from the ongoing enhance information maintained by the entity.  name string  UUID ~ 36 chars Progress ID Maintains a unique name for each enhance progress. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each enhance progress. rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. propertyId string  ~ 1024 chars Property ID to be enhanced The property ID of the GS2-Inventory item being enhanced. Identifies the specific item instance that will receive experience points upon completion of the enhancement. experienceValue long  0 ~ 9223372036854775805 Experience value obtainable The base experience value calculated from the consumed materials. This value is determined by summing the experience values defined in each material’s metadata, multiplied by the material quantity. rate float  0 ~ 100.0 Experience value scale factor The bonus multiplier applied to the base experience value. Determined by weighted lottery from the Enhancement Rate Model’s bonus rates. A value of 1.0 means no bonus, while values greater than 1.0 represent a “great success” bonus (e.g., 1.5 for 150% experience). EzRateModel Enhancement Rate Model The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity.  name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model. acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy. acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ] Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix. EzUnleashRateModel Unleash Rate Model Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.  name string  ~ 128 chars Unleash Rate Model name Unleash Rate 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model. gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on. EzUnleashRateEntryModel Unleash Rate Entry Model Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade.  gradeValue long  1 ~ 1000 Target grade The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed. needCount int  1 ~ 1000 How many items of the same type to consume The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzMaterial Enhance Material Represents a material item to be consumed during an enhancement operation. Each material references a specific GS2-Inventory item set and specifies the quantity to consume. The experience value provided by the material is determined from the item model’s metadata.  materialItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of Item Set that will be used as materials for enhancement References the specific GS2-Inventory item set to consume as enhancement material. The item must belong to the material inventory model specified in the Enhancement Rate Model. count int 1 0 ~ 2147483645 Number of consumption The quantity of this material item to consume. The total experience gained from this material is calculated by multiplying the per-item experience value (from the item model metadata) by this count. EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getRateModel Get an enhancement rate model by name Retrieves a single enhancement rate model by specifying its name. The returned information includes which inventory the target item belongs to, which inventory the materials come from, how experience is calculated from materials, and the bonus rate probability table. Use this to display the details of a specific enhancement recipe — for example, showing the material requirements and possible bonus rates on a weapon’s enhance screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRateModel Enhanced Rate Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRateModels Get a list of enhancement rate models Retrieves all enhancement rate models registered in this namespace. A rate model defines an enhancement recipe — which items can be used as materials, how much experience each material gives, and whether there’s a chance for a bonus multiplier. Use this to build the enhancement UI, for example to show which weapons can be enhanced and what materials they accept. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Enhanced Rate Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getUnleashRateModel Get a limit break rate model by name Retrieves a single limit break (unleash) rate model by specifying its name. The returned information includes the target inventory, the grade model used for tracking the item’s grade, and the list of grade entries that define the material requirements for each grade level. Use this to display the details of a specific limit break recipe — for example, showing “Grade 1 -\u003e 2: requires 1 duplicate” and “Grade 2 -\u003e 3: requires 2 duplicates” on an item detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzUnleashRateModel Unleash Rate Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listUnleashRateModels Get a list of limit break rate models Retrieves all limit break (unleash) rate models registered in this namespace. A limit break rate model defines how to raise an item’s grade (level cap) — for example, consuming duplicate copies of the same weapon to increase its maximum level. Each model specifies the materials required at each grade level, so the cost can increase as the item grows stronger. Use this to build a limit break UI that shows players which items can be limit-broken and what materials they need. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Unleash Rate Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. deleteProgress Cancel an in-progress enhancement Deletes the progress of the player’s in-progress enhancement, effectively canceling it. Note that materials consumed during Start are NOT refunded — only the pending experience grant is canceled. Use this if the player wants to cancel an enhancement, or use it to clean up before starting a different enhancement. Alternatively, you can set force to true when calling Start to automatically discard any existing progress. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzProgress Progress information for enhancement Implementation Example end Complete an enhancement (2-phase flow) Finishes the enhancement process that was started with the Start API. Takes the experience and bonus rate that were pre-calculated during Start and applies them to the target item. The progress is automatically deleted after completion. The result includes the acquired experience and bonus rate, so you can show a final result screen like “Enhancement complete! +1200 EXP”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzProgress progress information for enhancement transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example getProgress Get the current enhancement progress Retrieves the progress of the player’s in-progress enhancement. The progress contains the rate model name, target item, materials used, the pre-calculated experience, and the drawn bonus rate. Use this to restore the enhancement confirmation screen if the player leaves and comes back — for example, to re-display “You will gain +1200 EXP (Great Success x1.5)”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzProgress Progress information for the enhancement currently in the running Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. start Start an enhancement (2-phase flow) Begins the enhancement process by consuming materials and calculating the experience and bonus rate, but does NOT apply the experience yet. The calculated results are saved as progress, so you can show the player a preview — for example, “You will gain +1200 EXP (Great Success x1.5)” — before they confirm. After the player confirms, call End to actually apply the experience to the target item. If the player already has an in-progress enhancement, set force to true to discard it and start a new one. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List 0 ~ 10 items List of materials gameSession GameSession  GameSession force bool false If there is an enhancement that has already been started, it can be discarded and started, or config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the enhancement initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example enhance Enhance an item Consumes the specified materials to grant experience to the target item in a single step. The amount of experience gained is calculated based on the enhancement rate model, and a bonus multiplier may be drawn from the bonus rate probability table — for example, a “Great Success” that gives 1.5x experience. The result includes how much experience was gained and what bonus rate was applied, so you can display a result screen like “Weapon leveled up! +1200 EXP (Great Success x1.5)”. This is the simplest way to enhance — if you want to show the player the result before confirming, use the Start/End flow instead. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List  1 ~ 10 items List of Material config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzRateModel Enhanced Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to perform the enhancement process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Enhance SDK for Game Engine\n","title":"GS2-Enhance SDK for Game Engine API Reference","url":"/api_reference/enhance/game_engine/"},{"content":"Models EzAwait Exchange Await Represents the execution state of an exchange that requires real-time to elapse before rewards can be claimed. Created when a player initiates an exchange with await timing type, and tracks the waiting period until the rewards become available. Supports skip functionality to shorten or eliminate the waiting time, and stores default configuration values for reward acquisition.  userId string  ~ 128 chars User ID rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. skipSeconds int 0 0 ~ 2147483646 Skip seconds The number of seconds to subtract from the waiting time. When skip seconds are applied, the acquirableAt timestamp is moved earlier by this amount. Used to implement mechanics where players can pay resources to speed up the waiting process. config List [] 0 ~ 32 items Default configuration values applied when obtaining rewards Key-value pairs used as transaction placeholder variables when the await completes and rewards are distributed. These values are set at the time of exchange initiation and applied to the acquire actions’ transaction parameters. exchangedAt long Exchange time The timestamp when the exchange was initiated and the await was created. Used as the base time for calculating when rewards become available (acquirableAt = exchangedAt + lockTime - skipSeconds). acquirableAt long Time when rewards can be received The timestamp at which the waiting period expires and rewards become claimable. Calculated as exchangedAt + lockTime - skipSeconds. The player can call the acquire API once the current time has passed this timestamp. EzRateModel Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange.  name string  ~ 128 chars Exchange Rate Model name Exchange Rate 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. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. EzIncrementalRateModel Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis.  name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script consumeAction EzConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods acquire Claim the reward from a completed time-delayed exchange Claims the reward from a time-delayed exchange after the required wait time has passed. If the wait time hasn’t elapsed yet, this call will fail — check the remaining time first using GetAwait. Once claimed, the await record is consumed and the player receives the reward defined in the rate model. For example, after waiting 3 hours for an “Iron Sword” to be crafted, calling this gives the player the sword. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. Result Type Description item EzAwait Exchange Await transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward acquisition process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example deleteAwait Cancel a pending time-delayed exchange Deletes a pending exchange await record, effectively canceling the exchange. The reward will NOT be granted, and any resources already paid at the start of the exchange are NOT refunded. Use this when the player wants to cancel a pending craft or building order — make sure to show a confirmation dialog since the cost is not returned. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. Result Type Description item EzAwait Exchange Await Implementation Example getAwait Get a specific pending time-delayed exchange Retrieves the details of a specific exchange await record. The returned information includes the exchange type, how many were requested, when it was started, and how much wait time remains. Use this to show a detail screen for a specific pending exchange — for example, “Crafting Iron Sword… 2h 30m remaining”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. Result Type Description item EzAwait Exchange Await Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listAwaits Get a list of pending time-delayed exchanges Retrieves the player’s exchange await records — these are exchanges that require waiting before the reward can be claimed (like crafting or building). You can filter by rate name to show only awaits for a specific exchange type. Use this to build a “pending crafts” or “in-progress” list that shows the player what they’re waiting for and how much time is left. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of Exchange Awaits nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRateModel Get an exchange rate model by name Retrieves a single exchange rate model by specifying its name. The returned information includes what the player needs to pay, what they receive, and whether it’s an instant exchange or requires waiting. Use this to display the details of a specific exchange — for example, showing “Cost: 100 Gold -\u003e Reward: 1 Healing Potion” on a shop item detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRateModel Exchange Rate Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRateModels Get a list of exchange rate models Retrieves all exchange rate models registered in this namespace. A rate model defines an exchange recipe — what resources the player pays (e.g., 100 gold coins) and what they receive in return (e.g., 1 healing potion). There are two timing types: “immediate” exchanges happen instantly, while “await” exchanges require the player to wait a certain amount of time before claiming the reward (like crafting). Use this to build a shop or crafting UI that shows all available exchange options to the player. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Exchange Rate Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getIncrementalRateModel Get an incremental cost exchange rate model by name Retrieves a single incremental cost exchange rate model by specifying its name. The returned information includes the cost calculation method (linear formula or custom script), the base cost, the cost increase per exchange, the maximum number of exchanges allowed, and what the player receives. Use this to display the details of a specific incremental exchange — for example, showing “Stamina Refill: 30 gems (3rd purchase today, max 5)” on a shop screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzIncrementalRateModel Incremental Cost Exchange Rate Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listIncrementalRateModels Get a list of incremental cost exchange rate models Retrieves all incremental cost exchange rate models registered in this namespace. An incremental cost model defines an exchange where the price goes up each time the player uses it — for example, the first stamina refill costs 10 gems, the second costs 20 gems, the third costs 30 gems, and so on. The cost increase can be calculated using a simple linear formula (base + coefficient * count) or a custom script. Use this to build a UI that shows all available incremental exchanges and their current costs. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Incremental Cost Exchange Rate Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. exchange Perform an exchange Exchanges resources based on the specified rate model. The player pays the cost defined in the rate model and receives the reward — for example, trading 100 gold coins for 1 healing potion. You can specify a count to perform the same exchange multiple times at once (e.g., buy 5 potions for 500 gold). If the rate model uses “await” timing, this starts a time-delayed exchange instead of completing immediately (see the Await APIs for claiming the reward later). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzRateModel Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example incrementalExchange Perform an incremental cost exchange Exchanges resources using a rate model where the cost goes up each time. The cost is automatically calculated based on how many times the player has already used this exchange — for example, the first stamina refill costs 10 gems, the second costs 20 gems, and so on. You can specify a count to perform multiple exchanges at once; the total cost will be the sum of each step’s price. Use this for mechanics like daily stamina refills, limited shop purchases, or anything where you want the price to escalate with repeated use. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). gameSession GameSession  GameSession count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzIncrementalRateModel Incremental Cost Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Exchange SDK for Game Engine\n","title":"GS2-Exchange SDK for Game Engine API Reference","url":"/api_reference/exchange/game_engine/"},{"content":"Models EzStatus Status Status is an entity that exists for each property ID. Holds the current experience and rank cap values. Property ID is a status-specific ID and can be set to any value by the developer. For GS2, it is recommended to use a value as the property ID that adds an experience point model suffix to the end of the Item Set GRN in GS2-Inventory or the Entry GRN in GS2-Dictionary that possesses experience points.  experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Cumulative experience gained The total experience value accumulated by this status. The current rank is derived from this value using the rank threshold table. Experience cannot be gained beyond the threshold corresponding to the current rank cap. rankValue long 0 0 ~ 9223372036854775805 Current Rank The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. nextRankUpExperienceValue long 0 0 ~ 9223372036854775805 Experience points required for the next rank-up The cumulative experience threshold needed to advance to the next rank. Returns 0 if the status has already reached the rank cap. Useful for displaying progress bars or remaining experience in the game UI. EzExperienceModel Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank.  name string  ~ 128 chars Experience Model name Experience 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThreshold EzThreshold  Rank Up Threshold References the threshold table that defines the cumulative experience values required for each rank. The number of entries in the threshold determines the maximum possible rank, and each entry’s value specifies the experience needed to reach the next rank. acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. EzThreshold Rank Up Threshold The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained.  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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireActionRate Reward Addition Table Defines a rank-based multiplier table that adjusts reward quantities based on the status’s current rank. Each entry in the table corresponds to a rank and specifies a multiplier applied to the acquisition amount. Supports both standard double-precision values and big number string representations for large-scale calculations.  name string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. mode string (enum) enum {   “double”,   “big” } “double” Reward addition table type Selects the numeric precision for the multiplier values. Use “double” for standard floating-point numbers (up to 2^48), or “big” for string-represented numbers supporting up to 1024 digits when large-scale calculations are needed. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 10000 items Amount added per rank (multiplier) An array of multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 10000 items Amount added per rank (multiplier) An array of string-represented multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “big” for calculations requiring large-number precision. * Required if mode is “big” EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getExperienceModel Get an experience model by name Retrieves a single experience model by specifying its name. The returned information includes the EXP required for each level (rank-up thresholds), the default max level, and the absolute max level. Use this to calculate and display level progress — for example, to show how much more EXP a player’s weapon needs to reach the next level, or what the max level is after limit breaking. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzExperienceModel Experience Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listExperienceModels Get a list of experience models Retrieves all experience models registered in this namespace. An experience model defines a leveling system — how much EXP is needed to reach each level, the default max level, and the absolute max level. Use this to build level-up related UI, such as showing “EXP to next level: 150/500” or displaying the level-up thresholds on a character detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Experience Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getStatus Get the level/EXP status of a specific item or character Retrieves the current level, EXP, and max level for a specific property owned by the player. The property is identified by the experience model name (which leveling system to use) and the property ID (which specific item or character). Use this to display a detail screen — for example, “Iron Sword Lv.15 — EXP: 3200/5000 — Max Lv: 50”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. Result Type Description item EzStatus Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getStatusWithSignature Get the level/EXP status with a tamper-proof signature Retrieves the same level/EXP information as GetStatus, but also returns a cryptographic signature that proves the data hasn’t been tampered with. This is useful when you need to verify the player’s level in a trusted way — for example, when using the level as a condition in other services, or when passing level data to an external system that needs to confirm its authenticity. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzStatus Status body string Object to be verified signature string signature Implementation Example listStatuses Get a list of the player’s level/EXP statuses Retrieves the player’s current level and EXP information for their items or characters. You can optionally filter by experience model name — if omitted, all statuses across all experience types are returned. Each status includes the current EXP, current level, and max level for a specific property (e.g., a weapon or character). Use this to build a list screen showing all of the player’s leveled items — for example, “Iron Sword Lv.15, Fire Staff Lv.8”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string ~ 128 chars Experience Model name gameSession GameSession  GameSession 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Experience SDK for Game Engine\n","title":"GS2-Experience SDK for Game Engine API Reference","url":"/api_reference/experience/game_engine/"},{"content":"Models EzMold Form Storage Area An entity that holds information organized by the game player. Form information can be stored multiple times per Form Storage Area, and the capacity—how many can be stored—can be set individually for each game player × Form Storage Area.  name string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. EzForm Form An entity representing formation status. Slots can be defined as areas that can be formed. For weapons and armor, slots can be represented as parts like “right hand”, “left hand”, “torso”, and “arms”. For parties, slots can be represented as positions like “front line”, “mid-line”, and “back line”.  name string  ~ 128 chars Form name The name of the mold model this form belongs to. Identifies which form model (slot configuration) applies to this form instance. index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List 0 ~ 10 items List of Slots The current slot assignments for this form. Each entry corresponds to a slot defined in the form model and holds the property ID of the resource assigned to that position. Slot names must match those defined in the form model. EzPropertyForm Property Form An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.  name string  ~ 128 chars Property Form name The name of the property form model that defines the slot configuration for this property form. Determines which slots are available for assignment. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List 0 ~ 10 items List of Slots The current slot assignments for this property form. Each entry corresponds to a slot defined in the property form model. For example, if the property form represents skill configuration for a piece of equipment, each slot might hold a different skill assignment. EzFormModel Form Model Form Model is an entity representing the configuration status. You can define slots as areas that can be formed. For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots.  name string  ~ 128 chars Form Model name Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. EzMoldModel Form Storage Area Model If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually.  name string  ~ 128 chars Form Storage Area Model name Form Storage Area 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. formModel EzFormModel  Form Model initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. EzPropertyFormModel Property Form Model An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.  name string  ~ 128 chars Property Form Model name Property Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. EzSlotModel Slot Model Defines a single slot within a form model. A slot represents an assignable position where a game resource (such as an item, character, or equipment) can be placed. The property regex validates what values can be assigned to the slot.  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyRegex string “.*” ~ 512 chars Regular expressions for values that can be set as properties A regex pattern that validates the property ID values assignable to this slot. For example, restricting to specific GS2-Inventory item GRNs or GS2-Dictionary entry GRNs. Defaults to “.*” which allows any value. metadata string ~ 512 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. EzSlot Slot Represents the actual assignment state of a single slot within a form. Each slot holds a property ID referencing the game resource (such as a GS2-Inventory item set or GS2-Dictionary entry) that the player has placed in that position.  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyId string ~ 1024 chars Property ID A developer-defined identifier referencing the game resource assigned to this slot. Typically a GS2-Inventory Item Set GRN, GS2-Dictionary Entry GRN, or other resource identifier. Must match the slot model’s propertyRegex pattern. metadata string ~ 1024 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. EzSlotWithSignature Signature Slot A slot assignment that includes a cryptographic signature proving the player owns the referenced resource. Used when updating forms to verify that the player actually possesses the item, entry, or other resource being placed in the slot, preventing unauthorized assignments.  name string  ~ 128 chars Slot Model name Slot Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyType string (enum) enum {   “gs2_inventory”,   “gs2_simple_inventory”,   “gs2_dictionary” }  Property Type Specifies the type of GS2 resource referenced by this slot. Determines how the signature is verified: GS2-Inventory item sets, GS2-Inventory simple items, or GS2-Dictionary entries each have different signature formats. Definition Description “gs2_inventory” GS2-Inventory::ItemSet “gs2_simple_inventory” GS2-Inventory::SimpleItem “gs2_dictionary” GS2-Dictionary::Entry body string ~ 1048576 chars Payload The serialized resource data obtained from the GS2 service that owns the resource. Contains the resource state information needed to verify the signature and confirm ownership. signature string ~ 1024 chars Signature that proves ownership of the resource referenced by the property ID A cryptographic signature generated by the GS2 service that owns the resource. Verified during form updates to ensure the player possesses the referenced item set, simple item, or dictionary entry. metadata string ~ 1024 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. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getMoldModel Get a specific loadout preset model by name Retrieves a single mold model by specifying its name. The returned information includes the linked form model (slot structure), the initial number of presets a player can save, and the maximum capacity after expansion. Use this to display details about a specific preset category — for example, showing “Equipment Presets: 3/5 used, expandable to 10” on a formation detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzMoldModel Form Storage Area Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listMoldModels Get a list of loadout preset models Retrieves all mold models registered in this namespace. A mold model defines a type of loadout preset storage — for example, “Equipment Presets” or “Party Presets” — including how many presets a player can save (initial capacity) and the maximum number after expansion. Each mold model is linked to a form model that defines the slot structure. Use this to show the player all available preset categories, such as “Equipment Sets (3/5 slots used)” on a formation management screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Form Storage Areas Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getMold Get a specific loadout preset storage by name Retrieves the player’s mold record for a specific mold model. The returned information includes the current capacity — how many preset slots the player has available in this category. Use this to check a specific preset category’s status — for example, showing “Equipment Presets: 3/5 slots” before letting the player create a new preset. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzMold Form Storage Area moldModel EzMoldModel Form Storage Area Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listMolds Get a list of the player’s loadout preset storages Retrieves all of the player’s mold (preset storage) records. Each mold tracks the current capacity — how many form presets the player can save in that category. For example, a player might have “Equipment Presets” with 3 out of 5 slots used, and “Party Presets” with 1 out of 3 slots used. Use this to build a formation management overview showing all preset categories and their usage. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Form Storage Area nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getFormModel Get the slot structure definition for a form Retrieves the form model associated with a specific mold model. A form model defines the available slots — for example, “weapon slot”, “armor slot”, “accessory slot” — that make up an equipment loadout or party formation. Each slot specifies what kind of item can be placed in it (from inventory, simple inventory, or dictionary). Use this to build the equipment or formation editing screen, so you know what slots are available and how to label them. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzFormModel Form Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. deleteForm Delete a saved loadout preset Deletes a form preset at the specified index within a mold, clearing all slot contents. The preset slot becomes empty and can be reused for a new loadout later. Use this when the player wants to remove a saved preset — for example, a “Delete Preset” button on the loadout detail screen. Consider showing a confirmation dialog since the action cannot be undone. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name gameSession GameSession  GameSession index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. Result Type Description item EzForm Form mold EzMold Form Storage Area moldModel EzMoldModel Form Storage Area Model formModel EzFormModel Form Model Implementation Example getForm Get a specific saved loadout preset Retrieves a single form preset by specifying the mold model name and the preset index (0, 1, 2, etc.). The returned information includes the contents of each slot — which items are equipped in each position. Use this to display a loadout detail screen — for example, showing “Preset 1: Weapon = Iron Sword, Armor = Steel Plate, Accessory = Speed Ring”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name gameSession GameSession  GameSession index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. Result Type Description item EzForm Form mold EzMold Form Storage Area moldModel EzMoldModel Form Storage Area Model formModel EzFormModel Form Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getFormWithSignature Get a loadout preset with a tamper-proof signature Retrieves a form preset along with a cryptographic signature that proves the data hasn’t been tampered with. This signature is required when updating the form from the client side using SetForm — you must first call this to get the current form and its signature, then submit changes along with that signature. Use this as the first step of the “edit loadout” flow: get the current preset with its signature, let the player make changes, then save with SetForm. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name gameSession GameSession  GameSession index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzForm Form body string Value to be signed signature string Signature mold EzMold Form Storage Area moldModel EzMoldModel Form Storage Area Model formModel EzFormModel Form Model Implementation Example listForms Get a list of saved loadout presets Retrieves all form presets the player has saved within a specific mold (preset storage category). Each form is a set of slots filled with item references — for example, Preset 1 might have “Iron Sword” in the weapon slot and “Steel Armor” in the armor slot. Use this to build a preset selection screen where the player can see and switch between their saved loadouts, like “Preset 1: Attack Build”, “Preset 2: Defense Build”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name gameSession GameSession  GameSession 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 List of Form nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. setForm Save changes to a loadout preset Updates the slot contents of a form preset — for example, changing the weapon slot from “Iron Sword” to “Flame Blade”. This requires a signature obtained from GetFormWithSignature to prevent tampering. The typical flow is: (1) call GetFormWithSignature to get the current form and signature, (2) let the player edit their loadout, (3) call this API with the new slot values and the signature. If the mold doesn’t have a form at the specified index yet, a new preset is created (as long as the mold has available capacity). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name gameSession GameSession  GameSession index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List  1 ~ 10 items List of Slot keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzForm Form mold EzMold Form Storage Area moldModel EzMoldModel Form Storage Area Model formModel EzFormModel Form Model Implementation Example getPropertyFormModel Get a specific per-item form model by name Retrieves a single property form model by specifying its name. The returned information includes the slot definitions — what slots are available (e.g., “weapon”, “armor”, “skill”) and what kind of items can be placed in each slot. Use this to build the equipment editing screen for a specific character or item — for example, when the player taps on a character to manage their gear. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzPropertyFormModel Property Form Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listPropertyFormModels Get a list of per-item form models Retrieves all property form models registered in this namespace. A property form model defines a slot structure for forms that are identified by a custom property ID (like a character ID or weapon ID) rather than being stored in numbered preset slots. This is useful when each character or item has its own individual equipment set — for example, “Hero’s equipment” or “Mage’s equipment” where the property ID is the character’s unique ID. Use this to show the player all available per-item form types on a formation management screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Property Form Model name Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. deletePropertyForm Delete a character’s or item’s equipment set Deletes the property form for a specific property ID, clearing all slot contents. After deletion, the character or item will have no equipment set — you can create a new one later by calling SetPropertyForm. Use this when the player wants to reset a character’s equipment to empty — for example, a “Clear All Equipment” button on the character detail screen. Consider showing a confirmation dialog since all equipped items will be unassigned. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. Result Type Description item EzPropertyForm Property Form propertyFormModel EzPropertyFormModel Property Form Model Implementation Example getPropertyForm Get a specific character’s or item’s equipment set Retrieves a single property form by specifying the property form model name and the property ID (e.g., character ID). The returned information includes the contents of each slot — which items are equipped in each position for that specific character or item. Use this to display a character’s equipment detail screen — for example, showing “Hero: Weapon = Flame Blade, Armor = Dragon Mail, Shield = Holy Shield”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. Result Type Description item EzPropertyForm PropertyForm propertyFormModel EzPropertyFormModel Form Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getPropertyFormWithSignature Get a character’s equipment set with a tamper-proof signature Retrieves a property form along with a cryptographic signature that proves the data hasn’t been tampered with. This signature is required when updating the property form from the client side using SetPropertyForm — you must first call this to get the current form and its signature, then submit changes along with that signature. Use this as the first step of the “edit character equipment” flow: get the current equipment with its signature, let the player make changes, then save with SetPropertyForm. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzPropertyForm Property Form body string Value to be signed signature string Signature propertyFormModel EzPropertyFormModel Property Form Model Implementation Example listPropertyForms Get a list of per-item equipment sets Retrieves all property form records the player has for a specific property form model. Unlike regular forms (which are stored in numbered preset slots), property forms are identified by a custom property ID — typically the ID of a character or item. For example, this returns “Hero’s equipment”, “Mage’s equipment”, “Archer’s equipment” where each character has their own individual gear setup. Use this to build an overview screen showing all characters and their equipment configurations. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name gameSession GameSession  GameSession 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 List of PropertyForm nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. setPropertyForm Save changes to a character’s or item’s equipment set Updates the slot contents of a property form — for example, changing the Hero’s weapon from “Iron Sword” to “Flame Blade”. This requires a signature obtained from GetPropertyFormWithSignature to prevent tampering. The typical flow is: (1) call GetPropertyFormWithSignature to get the current form and signature, (2) let the player edit the equipment, (3) call this API with the new slot values and the signature. If no property form exists for the given property ID yet, a new one is created automatically. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List  1 ~ 10 items List of Slot keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzPropertyForm Property Form proeprtyFormModel EzPropertyFormModel Property Form Model Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Formation SDK for Game Engine\n","title":"GS2-Formation SDK for Game Engine API Reference","url":"/api_reference/formation/game_engine/"},{"content":"Models EzProfile Profile The profile stores information about the game player. There are three types of profiles that can be set for each public range. friend The information that can be viewed by those with whom a friend relationship has been established. follow Content that can be viewed by followers. public Content that can be viewed by anyone  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. EzBlackList Blacklist Manages a list of users that the player has blocked. Blocked users are prevented from sending friend requests or follow requests to this player, providing a mechanism for players to control unwanted interactions.  userId string  ~ 128 chars User ID targetUserIds List 0 ~ 1000 items Blacklist user ID list The list of user IDs that this player has blocked. Blocked users cannot send friend requests or follow requests to this player. EzFollowUser Follow User Represents a user that the current user is following. Provides access to the followed user’s public profile and follower-level profile information, which is visible to followers but not to the general public.  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The followed user’s publicly visible profile information, accessible to all players. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to followers. It can contain more detailed information than the public profile. EzFriendUser Friend User Represents a user who has an established mutual friend relationship with the current user. Provides access to the friend’s public profile and friend-level profile information, which is only visible to confirmed friends.  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The friend’s publicly visible profile information, accessible to all players. friendProfile string ~ 1024 chars Profile for friends The friend’s profile information visible only to confirmed friends. Contains more private information than the public profile. EzFriendRequest Friend Request Represents a friend request between two players. Contains the sender’s user ID, the recipient’s user ID, and the sender’s public profile for display purposes.  userId string  ~ 128 chars User ID of the sender of the friend request targetUserId string  ~ 128 chars User ID to whom a friend request was sent publicProfile string ~ 1024 chars Public profile The public profile of the friend request sender. Included for display purposes so that the recipient can identify who is requesting friendship. EzPublicProfile Public Profile A read-only view of a user’s publicly visible profile information. Can be retrieved for any user without requiring a friend or follow relationship. Used for displaying player information in search results, leaderboards, or other public contexts.  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The user’s publicly visible profile content, accessible without requiring a friend or follow relationship. Methods getProfile Get the player’s own profile Retrieves the player’s own profile, including all three visibility levels: Public profile: visible to everyone (e.g., player name, avatar) Follower profile: visible only to players who follow you (e.g., play style, favorite team) Friend profile: visible only to mutual friends (e.g., real name, contact info) Use this to display the “My Profile” or “Edit Profile” screen where the player can see and manage all their profile information. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzProfile Profile Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getPublicProfile Get another player’s public profile Retrieves only the public portion of the specified player’s profile — the information that is visible to everyone regardless of follow or friend status. For example, this returns their display name, avatar, and level, but NOT their follower-only or friend-only profile data. Use this to show a player card or mini-profile when tapping on another player’s name in rankings, chat, or matchmaking results. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Result Type Description item EzPublicProfile Public Profile Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. updateProfile Update the player’s own profile Updates the player’s profile with three distinct visibility levels: publicProfile: information shown to all players (e.g., display name, level, avatar icon) followerProfile: extra information shown only to followers (e.g., “Looking for guild members!”) friendProfile: private information shown only to friends (e.g., Discord ID, schedule) Each field is a free-form string, so you can store any text or JSON data. Use this when the player edits their profile from a settings or profile edit screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. Result Type Description item EzProfile Profile updated Implementation Example describeFollowUsers Get a list of players the player is following Retrieves all players that the current player has followed. Following is a one-way relationship — you can follow someone without their approval, like a social media follow. If withProfile is set to true, each followed player’s follower-level profile is also returned (the extra info they share with followers). Use this to build a “Following” list screen where the player can see everyone they follow. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession withProfile bool false Whether to include profile information in the result limit int 30 1 ~ 1000 Number of data items to retrieve pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of users that the user follows nextPageToken string Page token to retrieve the rest of the listing Implementation Example follow Follow another player Adds the specified player to the current player’s follow list. Following is a one-way action that does not require the other player’s approval — it works like a social media follow. After following, the player can see the target player’s follower-level profile information (the extra details they share with followers). Use this for a “Follow” button on another player’s profile, in search results, or in ranking lists. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID of the person want to follow withProfile bool  false Get a profile together Result Type Description item EzFollowUser Followed user Implementation Example getFollowUser Check if a specific player is being followed Retrieves a specific player from the current player’s follow list. If the target player is in the follow list, their information is returned. If withProfile is true, their follower-level profile is also included. Use this to check whether the player is already following someone — for example, to toggle a “Follow / Unfollow” button on another player’s profile screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession withProfile bool false Whether to include profile information in the result targetUserId string  ~ 128 chars User ID Result Type Description item EzFollowUser Following user Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. unfollow Unfollow a player Removes the specified player from the current player’s follow list. After unfollowing, the player will no longer be able to see the target player’s follower-level profile information. Use this for an “Unfollow” button on a followed player’s profile or in the “Following” list screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID withProfile bool  false Get a profile together Result Type Description item EzFollowUser Unfollowed user Implementation Example deleteFriend Remove a player from the friend list Removes the specified player from the current player’s friend list, ending the mutual friendship. After removal, neither player will be able to see each other’s friend-level profile information. Use this for a “Remove Friend” button on a friend’s profile or detail screen. Consider showing a confirmation dialog since the other player will also lose the friendship. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID withProfile bool  false Get a profile together Result Type Description item EzFriendUser Friend deleted Implementation Example describeFriends Get the player’s friend list Retrieves all players who are mutual friends with the current player. Unlike following (one-way), friendship is a two-way relationship that is established when a friend request is accepted by both sides. If withProfile is set to true, each friend’s friend-level profile is also returned (the most private level of profile information). Use this to build a “Friends” list screen showing all of the player’s friends — for example, displaying their names, avatars, and online status. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession withProfile bool false Whether to include profile information in the result limit int 30 1 ~ 1000 Number of data items to retrieve pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of Friend nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getFriend Get a specific friend’s information Retrieves information about a specific player from the current player’s friend list. If withProfile is true, the friend’s friend-level profile (the most private tier of profile data) is also returned. Use this to display a friend’s detail screen — for example, showing their full profile, stats, and options like “Remove Friend” or “Send Message”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result Result Type Description item EzFriendUser Friend Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. deleteRequest Cancel a sent friend request Cancels a friend request that the player previously sent, before the other player responds. The request is removed from both the sender’s outbox and the recipient’s inbox. Use this for a “Cancel Request” button on the sent requests screen or on a player’s profile where a request is already pending. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID Result Type Description item EzFriendRequest Friend Request deleted Implementation Example describeSendRequests Get a list of outgoing friend requests Retrieves all friend requests that the current player has sent and are still waiting for a response. Each request shows who it was sent to and when. The player can cancel pending requests if they change their mind. Use this to build a “Sent Requests” screen — for example, showing “Waiting for PlayerB to respond… [Cancel]”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Friend Request nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSendRequest Get a specific outgoing friend request Retrieves the details of a friend request that the current player has sent to a specific player. Use this to display the status of a specific sent request — for example, checking whether a request to a particular player is still pending, or showing request details on a player profile screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID Result Type Description item EzFriendRequest Friend Request Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. sendRequest Send a friend request to another player Sends a friend request to the specified player. The request will appear in their inbox, and they can accept or reject it. If accepted, both players become mutual friends and can see each other’s friend-level profile. Note: if the player already has 1000 friends, the request cannot be sent. Also, if there are existing pending requests, the oldest unanswered request is automatically withdrawn to make room for the new one. Use this for a “Send Friend Request” button on another player’s profile or in search results. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID of the person want to be friend Result Type Description item EzFriendRequest Sent Friend Request Implementation Example accept Accept a friend request Accepts an incoming friend request from the specified player. Once accepted, a mutual friendship is established — both players are added to each other’s friend lists and can see each other’s friend-level profile information. Use this for the “Accept” button on a friend request notification or in the friend request inbox. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession fromUserId string  ~ 128 chars User ID Result Type Description item EzFriendRequest Accepted Friend Request Implementation Example describeReceiveRequests Get a list of incoming friend requests Retrieves all friend requests that other players have sent to the current player and are waiting for a response. Each request shows who sent it and when. The player can then accept or reject each one. Use this to build a “Friend Requests” inbox screen — for example, showing “PlayerA wants to be your friend! [Accept] [Reject]”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Friend request nextPageToken string Page token to retrieve the rest of the listing Implementation Example getReceiveRequest Get a specific incoming friend request Retrieves the details of a friend request from a specific sender. Use this to display a friend request detail screen — for example, showing the sender’s profile and when the request was sent, along with “Accept” and “Reject” buttons. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession fromUserId string  ~ 128 chars User ID Result Type Description item EzFriendRequest Friend request Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. reject Reject a friend request Rejects an incoming friend request from the specified player. The request is deleted and no friendship is established. The sender is not notified that the request was rejected. Use this for the “Reject” or “Decline” button on a friend request notification or in the friend request inbox. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession fromUserId string  ~ 128 chars User ID Result Type Description item EzFriendRequest Rejected friend request Implementation Example getBlackList Get the player’s block list Retrieves a list of user IDs that the current player has blocked. Blocked players cannot send friend requests to or follow the current player. Use this to build a “Blocked Players” management screen where the player can review and unblock people they’ve previously blocked. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List Blacklisted user ID list nextPageToken string Page token to retrieve the rest of the listing Implementation Example registerBlackList Block a player Adds the specified player to the current player’s block list. Once blocked, the target player will not be able to send friend requests to or follow the current player. Use this for a “Block” button on another player’s profile screen or in a report/moderation menu. This helps players protect themselves from unwanted interactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID Result Type Description item EzBlackList blacklist Implementation Example unregisterBlackList Unblock a player Removes the specified player from the current player’s block list. After unblocking, the target player will be able to send friend requests and follow the current player again. Use this for an “Unblock” button on the blocked players management screen or on a blocked player’s profile. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars User ID Result Type Description item EzBlackList Blacklist Implementation Example Event Handlers OnFollowNotification Push notification to be used when you are followed Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID fromUserId string User ID Implementation Example OnAcceptRequestNotification Push notification used when a friend request is approved Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID targetUserId string User ID Implementation Example OnRejectRequestNotification Push notification used when a friend request is rejected Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID targetUserId string User ID Implementation Example OnDeleteFriendNotification Push notification used when a friend is deleted Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID fromUserId string User ID Implementation Example OnReceiveRequestNotification Push notification used when a friend request is received Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID fromUserId string User ID Implementation Example OnCancelRequestNotification Push notification used when a friend request is canceled Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID fromUserId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Friend SDK for Game Engine\n","title":"GS2-Friend SDK for Game Engine API Reference","url":"/api_reference/friend/game_engine/"},{"content":"Models EzWebSocketSession WebSocketSession A WebSocket session is a persistent connection between a GS2 server and a client for real-time bidirectional communication. The client registers a user ID as an identifier to the server.  connectionId string  ~ 128 chars Connection ID The unique identifier assigned to this WebSocket connection. Used to identify the specific client connection when sending notifications. namespaceName string  ~ 128 chars Namespace name userId string  ~ 128 chars User ID Methods setUserId Register the player’s connection to receive server push notifications Links the current WebSocket connection to the player’s user ID so that the server can send real-time push notifications to this client. This is typically called right after the player logs in and connects to the server — without this step, the server won’t know which connection belongs to which player. The allowConcurrentAccess flag controls whether the same player can be connected from multiple devices at once: true: allows multiple simultaneous connections (e.g., playing on both phone and tablet) false: only one connection per player is allowed (e.g., to prevent duplicate logins — the old connection gets kicked) Use this as part of your game’s login/initialization flow to enable features like real-time chat notifications, friend request alerts, or match-found notifications. Request  namespaceName string  ~ 128 chars Namespace name gameSession GameSession  GameSession allowConcurrentAccess bool true Whether to allow connections from different clients at the same time sessionId string {allowConcurrentAccess} == false ~ 128 chars Specifies a session ID that allows reconnection when allowConcurrentAccess is false and the existing connection has the same session ID. * Enabled only if allowConcurrentAccess is false Result Type Description item EzWebSocketSession WebSocket session updated Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Gateway SDK for Game Engine\n","title":"GS2-Gateway SDK for Game Engine API Reference","url":"/api_reference/gateway/game_engine/"},{"content":"Models EzStatus Status A status is an entity that exists for each property ID and holds the value of the current grade. The property ID is a status-specific ID and can be set to any value by the developer. It is strongly recommended that the value be the same as the property ID of the GS2-Experience.  gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. EzGradeModel Grade Model A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade.  name string  ~ 128 chars Grade Model name Grade 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. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. gradeEntries List  1 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). EzGradeEntryModel Grade Entry Model Defines the mapping between a grade value and a rank cap for the linked GS2-Experience model. Each entry also specifies regex patterns for matching property IDs, enabling the system to determine which resources can be used for grade-up operations and how their property IDs are transformed.  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. rankCapValue long  0 ~ 9223372036854775805 Rank Cap Value The rank cap value to set in the linked GS2-Experience model when this grade is applied. When a player’s grade changes to the value corresponding to this entry, the rank cap of the associated experience status is automatically updated to this value, controlling the maximum achievable rank. EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireActionRate Reward Addition Table Defines a named multiplier table that scales reward amounts based on the current grade value. Each grade value maps to a multiplier applied to acquire actions in transactions, allowing higher-graded characters or equipment to receive proportionally more rewards. Supports both standard double-precision mode and big number mode for extremely large values.  name string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. mode string (enum) enum {   “double”,   “big” } “double” Reward Addition Table Type Selects the numeric precision mode for multiplier values. “double” mode uses standard floating-point numbers suitable for most cases. “big” mode uses string-represented numbers supporting up to 1024 digits, for games requiring extremely large value calculations. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 1000 items Multiplier List per Grade (double mode) An array of reward multipliers indexed by grade value, using double-precision floating-point numbers. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 1000 items Multiplier List per Grade (big mode) An array of reward multipliers indexed by grade value, using string-represented numbers for extended precision. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “big” for games requiring very large number calculations. * Required if mode is “big” EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getGradeModel Get a specific limit break / ascension model by name Retrieves a single grade model by specifying its name. The returned information includes the grade entries (which define how the max level increases at each grade), the default starting grade, and the reward multiplier rates. Use this to display the details of a specific limit break system — for example, showing “Iron Sword: Grade 2 → Max Lv 70, Grade 3 → Max Lv 80” or “Current reward bonus: x1.5”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model name Grade Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzGradeModel Grade Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGradeModels Get a list of limit break / ascension models Retrieves all grade models registered in this namespace. A grade model defines a “limit break” or “ascension” system — it controls how much the max level (rank cap) of an item or character increases as the player raises its grade. For example, a weapon at Grade 0 might have a max level of 50, but after limit breaking to Grade 1, the max level increases to 60, Grade 2 to 70, and so on. The model also defines reward multiplier rates, which can increase the amount of rewards based on grade level (e.g., a Grade 3 character earns 1.5x gold). Use this to build limit break or ascension UI — for example, showing “Grade 2/5 — Max Lv: 70 — Next: requires 3 copies”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Grade Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. applyRankCap Sync the max level with the current limit break grade Updates the max level (rank cap) in GS2-Experience to match the current grade (limit break level). For example, if a character was limit broken from Grade 2 (max Lv 70) to Grade 3 (max Lv 80), calling this ensures the Experience system knows the new max level is 80. This is useful when the grade was changed externally and the max level in Experience needs to be synchronized. Normally, the max level is updated automatically when grade changes, but you can call this manually if the data gets out of sync. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. Result Type Description item EzStatus Status experienceNamespaceName string GS2-Experience Namespace Name experienceStatus EzStatus GS2-Experience Status after addition Implementation Example getStatus Get the limit break / ascension status of a specific item or character Retrieves the current grade (limit break level) for a specific property owned by the player. The property is identified by the grade model name (which limit break system to use) and the property ID (which specific item or character). Use this to display a limit break detail screen — for example, “Iron Sword — Grade: ★3 — Max Lv: 80 — Next limit break requires 2 more copies”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. Result Type Description item EzStatus Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listStatuses Get a list of the player’s limit break / ascension statuses Retrieves the player’s current grade (limit break level) for their items or characters. You can optionally filter by grade model name — if omitted, all grade statuses across all grade types are returned. Each status includes the current grade value and which property (item or character) it belongs to. Use this to build a list showing all limit-broken items — for example, “Iron Sword ★3, Fire Staff ★1, Dragon Armor ★5”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string ~ 128 chars Grade Model name gameSession GameSession  GameSession 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Grade SDK for Game Engine\n","title":"GS2-Grade SDK for Game Engine API Reference","url":"/api_reference/grade/game_engine/"},{"content":"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.  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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 [] 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.  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.  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.  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.  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.  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.  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  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.  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  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  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGuildModels Get a list of guild type definitions Retrieves all guild models registered in this namespace. A guild model defines the rules for a type of guild — maximum number of members, role permissions (e.g., “Officer can kick members”), join policy (open/approval required), rejoin cooldown, and how many guilds a player can belong to at once. It also defines what happens when the guild master is inactive for too long (automatic succession to the most senior member). Use this to show the player what types of guilds exist when they’re browsing or creating a guild. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Guild Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. assume Get permission to act on behalf of the guild Obtains a guild access token that lets the player perform actions as the guild itself — such as updating guild settings, accepting join requests, or kicking members. The player must be a member of the guild, and the actions they can perform depend on their role permissions. This is a required first step before calling guild management APIs like UpdateGuild, AcceptRequest, RejectRequest, DeleteMemberFromGuild, etc. Think of it like “switching to guild management mode” — after calling this, use the returned token for subsequent guild operations. Request  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 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  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  1 ~ 100 items List of members to update Result Type Description item EzGuild Guild updated Implementation Example 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  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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 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  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 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  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 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGuilds Search for guilds to join Searches for guilds that the player can join, with optional filters for display name, attributes, and join policy. You can filter by up to 5 custom attributes (e.g., play style, language, activity level) and by join policy (open / approval required). You can also choose whether to include guilds that are already full. Note: only guilds updated in the last 24 hours appear in search results. If a guild should stay visible, call UpdateGuild periodically even if nothing changed. Use this to build a “Find Guild” screen with search filters and a list of matching guilds. Request  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 0 ~ 10 items List of guild operation policies to search for guild attributes2 List 0 ~ 10 items List of guild operation policies to search for guild attributes3 List 0 ~ 10 items List of guild operation policies to search for guild attributes4 List 0 ~ 10 items List of guild operation policies to search for guild attributes5 List 0 ~ 10 items List of guild operation policies to search for guild joinPolicies List 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 Definition Description “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 List of Guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example 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  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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 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  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 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  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 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listReceiveRequests Get a list of join requests received by the guild Retrieves all pending join requests that players have sent to this guild. This is called as the guild (use Assume first to get a guild access token). Each request includes who sent it and any message or metadata they attached. Use this to build a “Join Requests” screen in the guild management panel — for example, showing a list like “PlayerA wants to join (Message: Level 50 healer, daily active)”. Request  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 List of join request nextPageToken string Page token to retrieve the rest of the listing Implementation Example 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  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 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  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 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSendRequests Get a list of join requests the player has sent Retrieves all join requests that the player has sent to various guilds and are still pending. Each entry includes which guild the request was sent to and any metadata (message) attached to the request. Use this to build a “My Applications” or “Pending Requests” screen — for example, showing “Applied to Dragon Knights (pending), Applied to Star Alliance (pending)”. Request  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 List of join requests nextPageToken string Page token to retrieve the rest of the listing Implementation Example 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  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 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listJoinedGuilds Get a list of guilds the player belongs to Retrieves all guilds that the player is currently a member of. You can optionally filter by guild model name — if omitted, guilds of all types are returned. Each entry includes the guild name, when the player joined, and their current role. Use this to build a “My Guilds” screen showing the player’s guild memberships — for example, “Dragon Knights (Officer), Star Alliance (Member)”. Request  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 Joining guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. updateMemberMetadata Update your own member metadata in a guild Updates the player’s own metadata within a guild. Metadata is free-form text that can store any member-specific information. For example, you can use it to store the player’s preferred role (“Healer”), a personal message (“Looking for raid partners”), or gameplay preferences. Only the player themselves can update their own metadata — other members cannot change it. Use this for a “Edit My Guild Profile” feature where members can set their in-guild status or notes. Request  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 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  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 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  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 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  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 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  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listIgnoreUsers Get the guild’s block list Retrieves the list of players that the guild has blocked from joining. This is called as the guild (use Assume first to get a guild access token). Blocked players cannot send join requests to this guild — their requests are automatically rejected. Use this to build a “Blocked Players” management screen in the guild settings — for example, showing a list of blocked players with “Unblock” buttons. Request  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 List of User IDs that refuse to participate nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getLastGuildMasterActivity Check when the guild master was last active Retrieves the date and time of the guild master’s most recent activity. This is called as the guild (use Assume first to get a guild access token). Use this to display the guild master’s activity status — for example, “Guild Master last active: 3 days ago”. This information is useful for determining whether the guild master has been inactive long enough to trigger automatic succession (PromoteSeniorMember). Request  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 Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. promoteSeniorMember Replace an inactive guild master with the most senior member If the guild master has not been active for the period defined in the guild model’s inactivity settings, this promotes the longest-serving member to become the new guild master. This is called as the guild (use Assume first). The inactivity period threshold is configured in the guild model. This prevents guilds from becoming “stuck” when the guild master stops playing the game. Use this for a “Claim Leadership” button that appears when the guild master has been inactive — for example, showing “The guild master has been inactive for 30 days. As the most senior member, you can take over.” Request  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 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 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 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 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 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 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","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Guild SDK for Game Engine\n","title":"GS2-Guild SDK for Game Engine API Reference","url":"/api_reference/guild/game_engine/"},{"content":"Models EzStatus Status Created when GetIdleStatus is called for the first time, and the idle time count starts from that time. The idle time count is reset when you receive a reward. If GS2-Schedule events are associated, you cannot access Category before the event is held, and you cannot create a status. If an event is associated, the status holds the number of repetitions of the event. If the current event ID and the event ID at the time of status creation do not match, if the number of repetitions of the current event and the number of repetitions held by the status do not match, or if the status is created before the start time of the event, the waiting time is reset.  categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. randomSeed long 0 0 ~ 9223372036854775805 Random Seed A seed value used for deterministic random number generation when calculating idle rewards. Ensures that reward calculations are reproducible and consistent, allowing the server to verify reward results. Updated each time rewards are received. idleMinutes int  0 ~ 2147483646 Idle Minutes The accumulated idle time in minutes since the last reward claim or status creation. This value is calculated from the elapsed time since idleStartedAt and is capped at maximumIdleMinutes. The number of available rewards is determined by dividing this value by the category model’s rewardIntervalMinutes. maximumIdleMinutes int 0 0 ~ 2147483646 Maximum Idle Minutes The maximum idle time in minutes that this status can accumulate. Initialized from the category model’s defaultMaximumIdleMinutes when the status is created. Can be increased per-user via acquire actions, allowing premium users or event participants to accumulate more idle rewards. EzCategoryModel Category Model A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time.  name string  ~ 128 chars Category Model name Category 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action Represents a single acquire action used as an idle reward. Consists of an action type (e.g., add items, increase currency) and its request parameters. When idle rewards are claimed, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireActionList Acquire Action List A wrapper that groups multiple acquire actions to be granted together for a single reward interval. Each AcquireActionList corresponds to one reward cycle in the category model’s acquireActions array, enabling different reward combinations at each interval.  acquireActions List [] 0 ~ 100 items List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getCategoryModel Get a specific idle reward category definition by name Retrieves a single idle reward category model by specifying its name. The returned information includes the reward interval (how many minutes between each reward), the maximum idle time cap, what rewards are granted, and schedule settings. Use this to display the details of a specific idle reward type — for example, showing “Gold Mine — Earn 10 gold every 30 minutes — Max accumulation: 8 hours — Currently: 160 gold ready to claim”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzCategoryModel Category Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCategoryModels Get a list of idle reward category definitions Retrieves all idle reward categories registered in this namespace. A category model defines how AFK (idle) rewards work — how often rewards accumulate (e.g., every 10 minutes), the maximum idle time (e.g., up to 8 hours), what rewards the player gets, and whether the timer resets after claiming. You can also link categories to a schedule to control when idle rewards are active (e.g., only during weekday events). Use this to show the player what types of idle rewards are available — for example, “Gold Mine (10 gold every 30 min, max 8 hours)” and “XP Training (50 XP every hour, max 24 hours)”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getStatus Get the idle reward status for a specific category Retrieves the player’s idle reward status for a specific category. The status includes when the idle timer started and the current maximum idle time. If no status exists yet, it is automatically created with the current time as the start. Use this to display a specific idle reward’s progress — for example, “Gold Mine — Idling for 4h 30m / 8h max — 90 gold ready to claim”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. gameSession GameSession  GameSession Result Type Description item EzStatus Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listStatuses Get a list of the player’s idle reward statuses Retrieves all idle reward statuses for the player across all categories. Each status shows when the player started idling (when they last claimed rewards or when the timer started) and the current maximum idle time. Use this to build an “Idle Rewards” overview screen — for example, showing “Gold Mine: 4h 30m accumulated, XP Training: 1h 15m accumulated” with a “Claim” button for each. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. prediction Preview the idle rewards that can be claimed right now Calculates and returns the rewards the player would receive if they claimed right now, without actually claiming them. The reward amount is based on how long the player has been idling divided by the reward interval, capped by the maximum idle time. This does not reset the timer or grant any rewards — it’s a read-only preview. Use this to show what the player will get before they press the “Claim” button — for example, “You will receive: 90 Gold, 5 Gems”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. gameSession GameSession  GameSession Result Type Description items List Rewards status EzStatus Status Implementation Example receive Claim the accumulated idle rewards Claims the idle rewards that have accumulated based on the player’s idle time for the specified category. The reward amount is calculated from how long the player has been idling, divided by the reward interval, and capped by the maximum idle time. After claiming, the idle timer resets and starts accumulating again from zero. Use this for the “Claim Rewards” or “Collect” button on the idle rewards screen — for example, the player taps “Collect” and receives “90 Gold, 5 Gems” that accumulated while they were away. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. gameSession GameSession  GameSession Result Type Description items List Rewards status EzStatus Status updated transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Idle SDK for Game Engine\n","title":"GS2-Idle SDK for Game Engine API Reference","url":"/api_reference/idle/game_engine/"},{"content":"Models EzMessage Message Message data delivered to a message box prepared for each game player. Messages have an open state, and you can set an Acquire Action to be executed when opened. Messages can be set to expire, and messages that expire are automatically deleted regardless of whether they are unread or read after opening. Messages will be deleted even if you have not received the attached reward.  messageId string * ~ 1024 chars Message A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. metadata string  ~ 4096 chars Metadata Arbitrary data representing the message content, such as a JSON string containing the message title, body text, sender information, and display parameters. GS2 does not interpret this value; it is passed through to the game client for rendering the message UI. Maximum 4096 characters. isRead bool false Read Status Indicates whether the message has been opened by the user. When a message is opened, this flag is set to true, the readAcquireActions are executed to deliver attached rewards, and the readAt timestamp is recorded. If isAutomaticDeletingEnabled is set on the namespace, the message is deleted after being read. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions executed when the user opens this message. Used to attach rewards such as items, currency, or resources to messages. Multiple actions can be combined to grant different reward types simultaneously. Up to 100 actions per message. receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server readAt long 0 Datetime of read Unix time, milliseconds expiresAt long Expiration datetime Unix time, milliseconds EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action Represents a single acquire action attached to a message as a reward. Consists of an action type (e.g., add items to inventory, increase currency) and its request parameters. When a message is opened, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods batchRead Open multiple messages and claim all rewards at once Opens up to 10 messages at once and grants all their attached rewards in a single operation. If any of the specified messages has already been opened, an error is returned and none of the messages are processed — this ensures rewards are never claimed twice. Use this for an “Open All” or “Claim All” button on the gift box screen — the player taps one button and receives all pending rewards at once. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageNames List  1 ~ 10 items List of message names gameSession GameSession  GameSession Result Type Description items List List of Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result 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 MessageExpiredException NotFoundException Message has expired Implementation Example delete Delete a message from the gift box Permanently removes a message from the player’s gift box, regardless of whether it has been opened or not. If your gift box is configured to automatically delete messages when they are opened, you don’t need to call this manually. But if auto-delete is disabled (so that opened messages remain visible in the gift box), use this API to let players clean up their inbox. Use this for a “Delete” or “Dismiss” button on individual messages — for example, letting players remove old opened messages they no longer need. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. Result Type Description item EzMessage Message deleted Implementation Example get Get the details of a specific message Retrieves the full details of a specific message in the player’s gift box, including its metadata (title, body, etc.), read status, attached rewards, and expiration time. Use this to show a message detail screen — for example, “Maintenance Compensation — Sorry for the inconvenience! Here are 100 Gems as compensation. [Open]”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. gameSession GameSession  GameSession Result Type Description item EzMessage Message Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. list Get a list of messages in the player’s gift box Retrieves all messages in the player’s gift box (present box / inbox), ordered from newest to oldest. Each message can contain rewards (items, currency, etc.) that the player can claim by opening it. You can filter by read status — for example, showing only unopened messages or only opened ones. Use this to build a “Gift Box” or “Presents” screen — for example, showing a list like “Maintenance Compensation (Gems x100)”, “Daily Login Bonus (Gold x500)”, with an “Open” button for each. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession isRead bool Read status 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 List of Message nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. read Open a message and claim its rewards Opens the specified message and grants any attached rewards (items, currency, etc.) to the player. The message is marked as read and the rewards are delivered in a single operation. If the message has already been opened, an error is returned to prevent claiming rewards twice. If the message has no rewards attached, it is simply marked as read. Use this for the “Open” or “Claim” button on each message in the gift box — for example, the player taps “Open” and receives “Gems x100”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. gameSession GameSession  GameSession Result Type Description item EzMessage Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result 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 MessageExpiredException NotFoundException Message has expired Implementation Example receiveGlobalMessage Receive messages sent to all players Checks for global messages (messages sent to all players at once, such as maintenance compensation or event rewards) and delivers any that this player hasn’t received yet to their gift box. Each global message is converted into an individual message in the player’s inbox. Messages already received are skipped, so calling this multiple times is safe. Call this when the player opens the gift box screen or logs in, to make sure they have all global messages available. Use this as part of the gift box initialization — call it before listing messages to ensure the player sees all global gifts. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item List List of received messages Implementation Example Event Handlers OnReceiveNotification Push notification used when a message is received Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID messageName string Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Inbox SDK for Game Engine\n","title":"GS2-Inbox SDK for Game Engine API Reference","url":"/api_reference/inbox/game_engine/"},{"content":"Models EzInventory Inventory Inventory is like a bag that stores items owned by game players. The bag has a capacity, and the capacity can be expanded by each player.  inventoryId string * ~ 1024 chars Inventory A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. currentInventoryCapacityUsage int 0 0 ~ 2147483646 Capacity Usage The number of inventory slots currently occupied by item sets. Incremented when a new item stack is added (e.g., when allowMultipleStacks creates a new slot) and decremented when an item set is fully consumed or deleted. Cannot exceed currentInventoryMaxCapacity. currentInventoryMaxCapacity int  1 ~ 2147483646 Maximum Capacity The current maximum number of inventory slots available to this user. Initialized from the inventory model’s initialCapacity and can be expanded up to the model’s maxCapacity through acquire actions or direct API calls. EzItemSet Item Set Item Set represents the possessions stored in the game player’s inventory. Item Set holds the Inventory Model name, Item Model name, quantity held, expiration time, and other details.  itemSetId string * ~ 1024 chars Item Set A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. count long  1 ~ 9223372036854775805 Quantity in Possession The number of items in this stack. Ranges from 1 to the item model’s stacking limit. When items are acquired, this count increases up to the stacking limit; when consumed, it decreases. If count reaches 0, the item set is deleted and the inventory slot is freed. sortValue int  0 ~ 2147483646 Display Order A numeric value copied from the item model’s sortValue, used to sort item sets within the inventory for display purposes. Lower values are displayed first. expiresAt long 0 Expiration time Unix time, milliseconds referenceOf List [] 0 ~ 24 items List of References The external references registered on this item set. Used to track which systems are using this item (e.g., equipped as weapon, assigned to formation). Up to 24 references per item set. EzSimpleItem Simple Item Simple Item represents a possession stored in the game player’s inventory. Simple Item has a model name and the quantity possessed.  itemId string * ~ 1024 chars Simple Item A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  0 ~ 9223372036854775805 Quantity in Possession The number of this item type held by the user. Unlike standard inventory items, simple items have no stacking limit and the count can be any value within the int64 range. Can be increased or decreased through batch operations along with other simple items. EzBigItem Big Item Big item represents possessions stored in the game player’s Big Inventory. Big Items can hold quantities beyond the range of int64.  itemId string * ~ 1024 chars Big Item A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. count string BigInteger (Unity)  ~ 1024 chars Quantity in possession Integer value strings up to 1024 digits EzInventoryModel Inventory Model Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity.  name string  ~ 128 chars Inventory Model name Inventory 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. EzItemModel Item Model Items can be held in groups within a single inventory slot, such as Potion ×99. This grouping of multiple items into one slot is called “stacking,” and a maximum stack size can be set for each item. The behavior when the stack limit is reached can also be set for each item. Specifically, you can choose one of the following: Add a new inventory slot to allow further acquisition Prevent further acquisition once the limit is reached  name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. EzSimpleInventoryModel Simple Inventory Model In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation.  name string  ~ 128 chars Simple Inventory Model name Simple Inventory 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. EzSimpleItemModel Simple Item Model ItemModel allowed setting a maximum stackable quantity, enabling implementation where items exceeding a certain number could be split into multiple stacks. SimpleItem does not have such a function and simply stores the number of items in the possession of the item.  name string  ~ 128 chars Simple Item Model name Simple Item 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. EzBigInventoryModel Big Inventory Model In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits.  name string  ~ 128 chars Big Inventory Model name Big Inventory 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. EzBigItemModel Big Item Model The Big Item Model defines items stored in a Big Inventory Model. Big Items can hold quantities that exceed the range of int64.  name string  ~ 128 chars Big Item Model name Big Item 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. EzConsumeCount Consumption quantity of Simple Item  itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  1 ~ 9223372036854775805 Consumption quantity EzAcquireCount Acquisition quantity of Simple Item  itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  1 ~ 9223372036854775805 Acquisition quantity Methods getInventoryModel Get a specific inventory type definition by name Retrieves a single inventory model by specifying its name. The returned information includes the initial and maximum capacity, item protection settings, and all item models that belong to this inventory. Use this to display the details of a specific inventory type — for example, showing “Equipment Bag — Capacity: 50/100 — Items: Iron Sword, Steel Shield, Leather Armor, …”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzInventoryModel Inventory Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listInventoryModels Get a list of inventory type definitions Retrieves all inventory models registered in this namespace. An inventory model defines a container type for items — such as “Equipment Bag”, “Material Pouch”, or “Consumable Box”. Each model sets the initial and maximum capacity (how many different item types it can hold), and includes the list of item models (what items can be stored in it). Use this to display what kinds of inventories the player has — for example, showing tabs like “Equipment (50/100 slots)”, “Materials (30/200 slots)”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Inventory Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getItemModel Get a specific item definition by name Retrieves a single item model by specifying the inventory name and item name. The returned information includes the maximum stack size, whether the item supports multiple stacks (e.g., items with different expiration dates are stored in separate stacks), and the sort order. Use this to display item rules — for example, showing “Healing Potion — Max per stack: 99 — Can have multiple stacks with different expiration dates”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzItemModel Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listItemModels Get a list of item definitions in an inventory Retrieves all item models that belong to the specified inventory. An item model defines the rules for a specific item type — such as the maximum stack size (e.g., potions stack up to 99), whether items can be split into multiple stacks, and the sort order for display. Use this to show what types of items can exist in an inventory — for example, listing all equipment types in the “Equipment Bag” or all materials in the “Material Pouch”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Item Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getInventory Get a specific inventory’s details Retrieves the details of a specific inventory by name, including the current capacity usage (used slots / max slots). Use this to display a specific inventory’s status — for example, showing “Equipment Bag — 45 / 100 slots used” at the top of the equipment inventory screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. gameSession GameSession  GameSession Result Type Description item EzInventory Inventory Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listInventories Get a list of the player’s inventories Retrieves all inventories that belong to the player. Each inventory shows its current capacity usage — how many item types (slots) are currently used out of the maximum capacity. Use this to build an inventory overview screen — for example, showing “Equipment Bag: 45/100 slots used”, “Material Pouch: 120/200 slots used” as a list of the player’s item containers. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Inventories nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. consume Use (consume) items from the player’s inventory Reduces the quantity of a specific item in the player’s inventory. Use this when the player uses or spends items through game-specific logic. For example, use this when the player uses a healing potion in battle, consumes crafting materials, or spends items on a custom game feature. Note: if items are consumed as a cost for purchasing products (GS2-Showcase) or starting quests (GS2-Quest), those systems handle item consumption automatically — you don’t need to call this API for those cases. You can optionally specify which stack (itemSetName) to consume from. If omitted, items are consumed from the oldest stack first. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. gameSession GameSession  GameSession consumeCount long  1 ~ 9223372036854775805 Consumption quantity itemSetName string ~ 36 chars Name identifying the Item Set Result Type Description items List List of Item Sets per post-consumption itemModel EzItemModel Item Model inventory EzInventory Inventory 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 ConflictException ConflictException Item manipulation process conflicted. Retry required. InsufficientException BadRequestException Insufficient quantity of items in your possession. Implementation Example getItem Get a specific item by inventory name and item name Retrieves all stacks of a specific item type that the player owns in the specified inventory. The response may contain multiple stacks (item sets) for the same item — items with different expiration dates are always in separate stacks. For example, requesting “Healing Potion” might return two stacks: one with 50 potions expiring soon and another with 30 potions expiring later. Use this to display an item detail screen — for example, showing “Healing Potion — Total: 80 — Stack 1: 50 (expires 2024-03-01), Stack 2: 30 (expires 2024-03-15)”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. gameSession GameSession  GameSession Result Type Description items List List of Item Sets itemModel EzItemModel Item Model inventory EzInventory inventory Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getItemWithSignature Get an item with a cryptographic signature proving ownership Retrieves an item set along with a server-signed signature that proves the player owned this item at the time of the API call. This is useful when you need to verify item ownership on an external server or another system — the signature serves as tamper-proof evidence. For example, you can use this to verify that a player actually owns a specific weapon before allowing them to enter a special dungeon. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. gameSession GameSession  GameSession itemSetName string ~ 36 chars Name identifying the Item Set keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description items List List of Item Sets itemModel EzItemModel Item Model inventory EzInventory Inventory body string Item Set Information for Signature Subject signature string Signature Implementation Example listItems Get a list of items the player owns in an inventory Retrieves all items that the player currently owns in the specified inventory. Each entry is an “item set” — a stack of items with a quantity and optionally an expiration date. The same item type can appear as multiple stacks if it has different expiration dates. For example, “Healing Potion” might show up as two entries: “Healing Potion x50 (expires in 3 days)” and “Healing Potion x30 (expires in 7 days)”. Use this to build the main item list screen for an inventory — showing all owned items with their quantities. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Item Sets nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSimpleInventoryModel Get a specific simple inventory type definition by name Retrieves a single simple inventory model by specifying its name. The returned information includes the list of simple item models that belong to this inventory — defining what items can be stored and their properties. Use this to display what a specific simple inventory contains — for example, showing the item types in a “Currency” or “Materials” inventory. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSimpleInventoryModel Simple Inventory Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSimpleInventoryModels Get a list of simple inventory type definitions Retrieves all simple inventory models registered in this namespace. A simple inventory is a lightweight version of the standard inventory — it stores items as simple name-and-count pairs without stacking, expiration dates, or capacity limits. Simple inventories are ideal for resources like currencies, crafting materials, or any item that just needs a count — for example, “Gold: 5000”, “Iron Ore: 150”, “Stamina Potion: 12”. Use this to see what types of simple inventories are available in the game. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Simple Inventory Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSimpleItemModel Get a specific simple item definition by name Retrieves a single simple item model by specifying the inventory name and item name. Use this to display the definition of a specific simple item type — for example, to show the properties of “Gold” or “Iron Ore” in the game UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSimpleItemModel Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSimpleItemModels Get a list of simple item definitions in an inventory Retrieves all simple item models that belong to the specified simple inventory. A simple item model defines a single item type that is tracked by count only — no stacking rules, no expiration, just a name and a number. Use this to see what items can exist in a simple inventory — for example, listing “Gold”, “Gems”, “Iron Ore”, “Wood” in the “Materials” inventory. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Simple Item Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. consumeSimpleItems Use (consume) simple items from the player’s inventory Reduces the quantity of one or more simple items in the player’s inventory. You can consume multiple item types at once in a single call. Use this when the player spends resources through game-specific logic — for example, spending crafting materials to forge a weapon, or using consumable items in battle. Note: if items are consumed as a cost for purchasing products (GS2-Showcase) or starting quests (GS2-Quest), those systems handle item consumption automatically — you don’t need to call this API for those cases. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items Result Type Description items List List of Simple Items per post-consumption 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 ConflictException ConflictException Item manipulation process conflicted. Retry required. InsufficientException BadRequestException Insufficient quantity of items in your possession. Implementation Example getSimpleItem Get the count of a specific simple item Retrieves how many of a specific simple item the player currently owns. Use this to check a specific resource amount — for example, displaying “Gold: 5,000” on the shop screen before a purchase, or “Iron Ore: 150/200 needed” on the crafting screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. gameSession GameSession  GameSession Result Type Description item EzSimpleItem Simple Item itemModel EzSimpleItemModel Simple Item Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSimpleItemWithSignature Get a simple item with a cryptographic signature proving ownership Retrieves a simple item along with a server-signed signature that proves the player owned this item at the time of the API call. This is useful when you need to verify item ownership on an external server or another system — the signature serves as tamper-proof evidence. For example, you can use this to verify that a player has enough currency or materials before processing a trade on an external marketplace. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. gameSession GameSession  GameSession keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzSimpleItem Simple Item simpleItemModel EzSimpleItemModel Simple Item Model body string Simple Item Information for Signature Subject signature string Signature Implementation Example listSimpleItems Get a list of simple items the player owns in an inventory Retrieves all simple items that the player currently owns in the specified simple inventory. Each item is a simple name-and-count pair — for example, “Gold: 5000”, “Iron Ore: 150”. Unlike standard inventory items, simple items have no stacking, expiration, or slot limits. Use this to display a resource or material list — for example, showing the player’s currency balance, crafting materials, or consumable counts. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Simple Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getBigInventoryModel Get a specific big inventory type definition by name Retrieves a single big inventory model by specifying its name. The returned information includes the list of big item models that belong to this inventory. Use this to display the details of a specific big inventory type — for example, showing what items are tracked in the “Mega Currency” or “Accumulated Points” inventory. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzBigInventoryModel Big Inventory Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBigInventoryModels Get a list of big inventory type definitions Retrieves all big inventory models registered in this namespace. A big inventory is designed for items that can have extremely large quantities — beyond what normal integers can handle (e.g., billions or trillions). This is useful for idle/incremental game currencies, accumulated points, or any resource that can grow to very large numbers. Use this to see what types of big inventories are available in the game. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Big Inventory Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getBigItemModel Get a specific big item definition by name Retrieves a single big item model by specifying the inventory name and item name. Use this to display the definition of a specific big item type — for example, to show the properties of “Mega Gold” or “Lifetime XP” in the game UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzBigItemModel Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBigItemModels Get a list of big item definitions in an inventory Retrieves all big item models that belong to the specified big inventory. A big item model defines an item type that can hold extremely large quantities using arbitrary-precision numbers (stored as strings instead of integers). Use this to see what items can exist in a big inventory — for example, listing “Mega Gold”, “Lifetime XP”, “Total Damage Dealt” in the game. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Big Item Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. consumeBigItem Use (consume) a big item from the player’s inventory Reduces the quantity of a specific big item in the player’s inventory. The consume count is specified as a string to support extremely large values. Use this when the player spends big-number resources through game-specific logic — for example, spending “1,000,000,000 Mega Gold” on a prestige upgrade or consuming accumulated points. Note: if items are consumed as a cost for purchasing products (GS2-Showcase) or starting quests (GS2-Quest), those systems handle item consumption automatically — you don’t need to call this API for those cases. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits Result Type Description item EzBigItem Big Item per post-consumption 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 ConflictException ConflictException Item manipulation process conflicted. Retry required. InsufficientException BadRequestException Insufficient quantity of items in your possession. Implementation Example getBigItem Get the count of a specific big item Retrieves the current count of a specific big item the player owns. The count is returned as a string to support extremely large values. Use this to check a specific big-number resource — for example, displaying “Mega Gold: 1,234,567,890” on the game’s main screen or “Lifetime XP: 9,876,543,210” on the player profile. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. gameSession GameSession  GameSession Result Type Description item EzBigItem Big Item itemModel EzBigItemModel Big Item Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBigItems Get a list of big items the player owns in an inventory Retrieves all big items that the player currently owns in the specified big inventory. Each item has a count stored as a string to support extremely large numbers (e.g., “1234567890123456789”). Items that have never been acquired will not appear in the results. Use this to display the player’s big-number resources — for example, showing “Mega Gold: 1,234,567,890” or “Total Damage: 9,876,543,210,000”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Quantity of Big Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Inventory SDK for Game Engine\n","title":"GS2-Inventory SDK for Game Engine API Reference","url":"/api_reference/inventory/game_engine/"},{"content":"Models EzJob Job A job queue is a mechanism for delaying the execution of a process rather than completing it immediately. For example, when a character is acquired, the process that must be executed immediately is to store the character in the inventory. On the other hand, a process that does not have to be executed immediately is the process of registering the character to the dictionary . By processing tasks that do not need to be executed immediately through a job queue, the system can be made more fault-tolerant. This is because even if the dictionary service is stopped due to some failure, the game can continue without being registered in the dictionary. Even if the process enqueued in the job queue fails, it can be retried after the failure is resolved, resulting in a correct state. GS2 recommends this kind of eventual consistency process, and in various situations, job queues are used for delayed processing.  jobId string * ~ 1024 chars Job A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN args string  ~ 5242880 chars Argument The JSON-formatted request parameters to pass to the script when the job is executed. Contains the specific operation details such as action type and target resources. Maximum 5MB. currentRetryCount int 0 0 ~ 100 Current Retry Count The number of times this job has been retried after failure. Incremented each time execution results in a retryable error. When this count reaches maxTryCount, the job is marked as permanently failed. maxTryCount int 3 1 ~ 100 Maximum Number of Attempts The maximum number of times this job can be executed, including the initial attempt and retries. If all attempts fail, the job is abandoned. Default is 3, maximum is 100. EzJobResult Job Execution Results Records the outcome of a single job execution attempt. Each attempt creates a separate JobResult, so a job that is retried multiple times will have multiple results. The statusCode indicates whether the job succeeded or failed.  statusCode int  0 ~ 1000 Status Code The HTTP status code returned by the script execution. A 2xx code indicates success, and other codes indicate failure. Retryable errors may trigger automatic retry if maxTryCount has not been reached. result string  ~ 5242880 chars Response Content The JSON-formatted response body returned by the script execution. Contains the result data on success or error details on failure. Maximum 5MB. EzJobEntry Register Job Represents the parameters for registering a new job to the job queue. Contains the script to execute, the JSON arguments, and the maximum retry count. Used as input when pushing jobs onto the queue.  scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN args string “{}” ~ 131072 chars Argument The JSON-formatted request parameters to pass to the script when the job is executed. Defaults to an empty JSON object “{}”. Maximum 128KB. maxTryCount int 3 0 ~ 100 Maximum Number of Attempts The maximum number of times the job can be executed, including the initial attempt and retries. Default is 3, maximum is 100. EzJobResultBody Job Execution Result Body A lightweight representation of a job execution result, containing the attempt number, status code, response content, and execution timestamp.  tryNumber int  1 ~ 10000 Try Number The sequential attempt number for this execution result, starting from 1. Used to identify which retry attempt produced this result. statusCode int  0 ~ 1000 Status Code The HTTP status code returned by the script execution. A 2xx code indicates success, and other codes indicate failure. Retryable errors may trigger automatic retry if maxTryCount has not been reached. result string  ~ 5242880 chars Response Content The JSON-formatted response body returned by the script execution. Contains the result data on success or error details on failure. Maximum 5MB. tryAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Methods run Run the next job in the player’s job queue GS2 uses job queues to handle deferred processing — for example, when a player obtains a character, the character is immediately added to their inventory, but registering it in the encyclopedia can be processed later via a job queue. This design makes the game more resilient: even if a related service is temporarily down, the game can continue, and the queued jobs will be retried and completed once the service recovers. When you call this API, it executes the next pending job in the player’s queue and returns the result. The response includes an isLastJob flag — if it is false , there are more jobs waiting, so keep calling this API in a loop until isLastJob becomes true . You can also set up push notifications on the namespace so your game client is notified whenever a new job is added — this way, you don’t need to poll and can simply call this API when notified. If the namespace has enableAutoRun turned on, jobs are executed automatically on the server side, so calling this API is not required. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzJob Job result EzJobResultBody Job execution result body isLastJob bool 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 ConflictException ConflictException Job queue execution conflict. Retry required. Implementation Example getResult Get the result of a completed job Retrieves the execution result of a specific job by its name. The result includes a status code indicating success or failure and the response body returned by the job. This is useful when you want to check whether a deferred process (such as registering to an encyclopedia or distributing rewards) completed successfully. If a job was retried multiple times, you can specify a try number to see the result of a particular attempt. Note: Job results are kept for a limited time after execution and may be automatically cleaned up. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. Result Type Description item EzJobResult Job execution result Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnPushNotification Push notification used when a job is registered in the job queue Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID Implementation Example OnRunNotification Push notification used when a job in the job queue is executed Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID jobName string Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-JobQueue SDK for Game Engine\n","title":"GS2-JobQueue SDK for Game Engine API Reference","url":"/api_reference/job_queue/game_engine/"},{"content":"Models EzCounter Current Counter Value Tracks the current usage count for a specific counter under a limit model for each user. Multiple counters can exist under a single limit model (e.g., one counter per quest for one-time rewards). The count is compared against a maximum value specified at the time of the count-up operation, and is automatically reset to zero based on the limit model’s reset schedule.  counterId string * ~ 1024 chars Counter A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. name string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. count int 0 0 ~ 2147483646 Count Value The current usage count for this counter. Incremented by the countUp operation and compared against the maximum value specified at that time. Automatically reset to zero when the limit model’s reset timing is reached. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzLimitModel Usage Limit Model Usage Limit Model allows you to set the timing for resetting the usage count. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. Additionally, the maximum value for usage Limits is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha: Items purchasable when the purchase counter is under 3 When the above items are unavailable, another item purchasable if the purchase counter is under 5 The design assumes the ability to switch the “maximum count” based on the situation.  limitModelId string * ~ 1024 chars Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Usage Limit Model name Usage Limit 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days” Methods countUp Increment a usage limit counter Increases the specified counter by the given amount. If the counter would exceed the maximum value, the operation fails — this is how the usage limit is enforced. For example, if a daily purchase limit is set to 3 and the player has already purchased twice, counting up by 1 succeeds (total: 3). But trying to count up again would fail because it would exceed the limit. You can specify both the increment amount (countUpValue) and the maximum allowed value (maxValue). Use this when the player performs a limited action — for example, when they make a daily shop purchase or enter a limited dungeon. If the count up fails, it means the player has reached their limit. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. gameSession GameSession  GameSession countUpValue int 1 1 ~ 2147483646 Amount to count up maxValue int 1 ~ 2147483646 Maximum value allowed to count up Result Type Description item EzCounter Counter with increased count 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 OverflowException BadRequestException The maximum number of times limit has been reached. Implementation Example getCounter Get a specific usage limit counter Retrieves a specific counter by specifying the limit model name and counter name. The counter shows how many times the player has performed this specific action in the current period. Use this to check the remaining attempts for a specific action — for example, displaying “Daily Dungeon: 3/5 attempts used — 2 remaining” on a dungeon entry screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. gameSession GameSession  GameSession Result Type Description item EzCounter Counter Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCounters Get a list of the player’s usage limit counters Retrieves all usage limit counters for the player, showing how many times they have performed each limited action. You can optionally filter by limit model name — if omitted, counters for all limit types are returned. Each counter tracks the current count for a specific action (e.g., “Daily Shop Purchase: 2/3 used today”). Use this to build a “Remaining Attempts” or “Daily Limits” overview screen — for example, showing “Shop purchases: 2/3, Dungeon entries: 1/5, Free gacha: 0/1”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getLimitModel Get a specific usage limit definition by name Retrieves a single usage limit model by specifying its name. The returned information includes the reset type (not reset / daily / weekly / monthly) and related settings. Use this to display the rules of a specific limit — for example, showing “Daily Shop Limit — Resets every day at midnight” on a shop detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzLimitModel Usage Limit Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listLimitModels Get a list of usage limit definitions Retrieves all usage limit models registered in this namespace. A limit model defines how a usage counter works — most importantly, when it resets. Reset options include: Not reset: counter never resets (e.g., one-time first-clear bonus) Daily: resets every day (e.g., “buy up to 3 times per day”) Weekly: resets every week (e.g., weekly dungeon attempts) Monthly: resets every month (e.g., monthly reward claims) Use this to see what types of usage limits exist in the game — for example, to display “Daily Limits”, “Weekly Limits” categories in a shop or activity screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Usage Limit Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Limit SDK for Game Engine\n","title":"GS2-Limit SDK for Game Engine API Reference","url":"/api_reference/limit/game_engine/"},{"content":"Models EzMutex Mutex The mutex provided by GS2 is a type of re-entrant lock. When acquiring a lock, a transaction ID is specified, and the lock can be acquired again only if the same transaction ID is specified. Since it has a reference counter, the same number of unlock operations are required when releasing it.  mutexId string * ~ 1024 chars Mutex A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. ttlAt long The absolute time 1 hour after the current time Expiration datetime Unix time, milliseconds Methods get Get Mutex status Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. gameSession GameSession  GameSession Result Type Description item EzMutex Mutex Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. lock Obtaining a lock Locks the resource with the property ID for the number of seconds specified by ttl. The transaction ID must be specified when locking. Acquisition of a lock on the same property ID by a different transaction ID will fail. If the lock acquisition request is from the same transaction, the reference counter is increased. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. gameSession GameSession  GameSession transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. ttl long  0 ~ 9223372036854775805 Duration of lock acquisition (seconds) Result Type Description item EzMutex Mutex Implementation Example unlock Releasing a lock The lock must be released from the same transaction ID . If the lock is re-entered when the lock is acquired, the lock is released the same number of times, and the actual release occurs when the reference counter reaches zero. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. gameSession GameSession  GameSession transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. Result Type Description item EzMutex Mutex Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Lock SDK for Game Engine\n","title":"GS2-Lock SDK for Game Engine API Reference","url":"/api_reference/lock/game_engine/"},{"content":"Models EzInGameLog In-game Log A custom log entry sent from the game client or server-side scripts. Unlike access logs which are automatically generated by GS2 API calls, in-game logs are explicitly sent by game developers to record game-specific events such as player actions, game state changes, or business metrics.  timestamp long  Timestamp The date and time when the in-game log was sent. userId string ~ 128 chars User ID tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). payload string  ~ 10485760 chars Payload The custom log data in JSON format. Can contain any game-specific information such as player actions, game state, or business metrics. Maximum 10MB. EzInGameLogTag In-game Log Tag A key-value pair used to annotate in-game log entries for filtering and categorization. Each tag key must be unique within a single log entry.  key string  ~ 64 chars Tag Key The key name for this tag. Used as the filter criterion when searching in-game logs. value string  ~ 128 chars Tag Value The value for this tag. Combined with the key, enables filtering logs by specific criteria (e.g., key=“stageId”, value=“stage-001”). Methods sendInGameLog Send in-game logs Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). payload string  ~ 10485760 chars Payload The custom log data in JSON format. Can contain any game-specific information such as player actions, game state, or business metrics. Maximum 10MB. gameSession GameSession GameSession Result Type Description item EzInGameLog In-game log Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Log SDK for Game Engine\n","title":"GS2-Log SDK for Game Engine API Reference","url":"/api_reference/log/game_engine/"},{"content":"Models EzReceiveStatus Receive Status Tracks the login bonus receive status for each user per bonus model. Maintains a boolean array (receivedSteps) where each entry indicates whether the user has received the corresponding day’s reward. Also records the last time a bonus was received (lastReceivedAt) to determine daily eligibility. The receivedSteps can be reset when the bonus cycle restarts (e.g., in Streaming Mode with repeat enabled).  bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. receivedSteps List [] 0 ~ 100 items Received Steps An ordered boolean array where each element corresponds to a day in the reward list. true indicates the user has received that day’s reward; false indicates it was missed or not yet received. The array index aligns with the rewards array in the associated BonusModel. In Streaming Mode with repeat enabled, this array is reset when the cycle restarts. lastReceivedAt long Last Received At The timestamp of when the user last received a login bonus. Used to determine whether the user has already received today’s bonus based on the reset hour defined in the bonus model. Reset to 0 when the receive status is cleared (e.g., on cycle restart in repeat mode). EzBonusModel Login Bonus Model Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days.  name string  ~ 128 chars Login Bonus Model name Login Bonus 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. resetHour int {periodEventId} == \"\"  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” * [] 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” * [] 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” EzReward Reward Represents a single day’s reward configuration for a login bonus. Each Reward contains a list of acquire actions that define what the user receives (e.g., items, currency, experience). The rewards array in BonusModel holds one Reward per day, distributed in order. Reward values can be modified at runtime through the buff system (BonusModelBuff) to apply rate multipliers to acquire actions.  acquireActions List  1 ~ 10 items List of Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies an acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. EzConfig Configuration A key-value pair used to set values applied to transaction variables. Config entries allow dynamic parameterization of acquire actions at runtime. For example, slot names or other context-dependent values can be injected into transaction requests via Config settings, enabling flexible reward configuration without modifying the master data.  key string  ~ 64 chars Key The variable name to be replaced in transaction parameters. Maximum 64 characters. value string ~ 51200 chars Value The value to substitute for the corresponding key in transaction parameters. Maximum 51,200 characters. EzConsumeAction Consume Action Defines an action for consuming resources from a user via the transaction mechanism. Used in missed-bonus recovery to specify the cost users must pay (e.g., deducting currency, consuming items). The action field specifies the type of consume action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireAction Acquire Action Defines an action for granting resources to a user via the transaction mechanism. Used within rewards to specify what the user receives (e.g., adding items to inventory, granting currency, awarding experience points). The action field specifies the type of acquire action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods missedReceive Receive a missed login bonus Allows the player to retroactively claim a login bonus they missed on a previous day. This feature must be enabled on the bonus model (the “missed receive relief” setting). When enabled, the player can recover a missed reward by paying a cost — for example, spending 50 Gems to claim the reward they missed on Day 3. In Schedule Mode, only rewards up to the number of elapsed days since the event start can be recovered. In Streaming Mode, the step number can be automatically determined, so it can be omitted. This feature is not available when Streaming Mode has “repeat” enabled. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession stepNumber int 0 ~ 100 Step number to receive. In streaming mode, this can be omitted config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzReceiveStatus Receive status bonusModel EzBonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result 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 AlreadyReceivedException BadRequestException You have already received today’s login bonus. Implementation Example receive Receive today’s login bonus Claims the login bonus for the current day based on the specified bonus model. Each bonus model defines a sequence of daily rewards — for example, “Day 1: 100 Gems, Day 2: 5 Stamina Potions, Day 3: Rare Gacha Ticket, …”. The player progresses through the reward steps each day they log in and call this API. There are two modes: Schedule Mode: Rewards are tied to a specific calendar period. If the player misses a day, that day’s reward is skipped. Streaming Mode: Rewards are given in order from the beginning each time the player logs in, regardless of the calendar date. If the player has already received today’s bonus, an error is returned. When all rewards in the sequence have been given and “repeat” is enabled (Streaming Mode only), the cycle starts over from the first reward. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzReceiveStatus Receive status bonusModel EzBonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result 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 AlreadyReceivedException BadRequestException You have already received today’s login bonus. Implementation Example getBonusModel Get a specific login bonus schedule Retrieves the details of a single login bonus model by name. Use this to display the detail screen for a specific bonus schedule — for example, showing all 7 days of rewards with checkmarks on the days the player has already claimed. The returned model includes the full reward list, bonus mode, repeat settings, and missed-bonus recovery configuration. Combine this with GetReceiveStatus to know which days the player has already received and which are still available. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzBonusModel Login Bonus Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listBonusModels Get a list of all login bonus schedules Retrieves all login bonus models configured in the namespace. Each model defines a reward schedule — what the player receives on Day 1, Day 2, Day 3, and so on. Use this to build a login bonus overview screen that shows all available bonus schedules. For example, your game might have a “7-Day Newcomer Bonus” and a “Monthly Login Bonus” running at the same time — this API returns both. The returned models include the bonus mode (Schedule or Streaming), the list of daily rewards, whether repeat is enabled, and whether missed-bonus recovery is available. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Login Bonus Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getReceiveStatus Get the player’s login bonus progress for a specific bonus schedule Retrieves the receive status for a single login bonus model. The status includes a list of boolean values (receivedSteps) showing which days have been claimed — for example, [true, true, false, true, false, false, false] means “Day 1 and 2 claimed, Day 3 missed, Day 4 claimed, Day 5-7 not yet reached”. Use this together with GetBonusModel to build a detailed login bonus screen that shows each day’s reward alongside its claimed/unclaimed status. The response also includes the bonus model details, so you can display the reward information and receive status in a single API call. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. gameSession GameSession  GameSession Result Type Description item EzReceiveStatus ReceiveStatus bonusModel EzBonusModel Login Bonus Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listReceiveStatuss Get the player’s login bonus progress for all bonus schedules Retrieves the receive status for every login bonus model the player has interacted with. Each status tells you which days the player has already claimed and which are still available. Use this to build a login bonus overview screen — for example, showing “7-Day Newcomer Bonus: 4/7 claimed” and “Monthly Bonus: 12/30 claimed” with progress indicators. This is especially useful at game startup to check if there are any unclaimed bonuses to prompt the player. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of ReceiveStatuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-LoginReward SDK for Game Engine\n","title":"GS2-LoginReward SDK for Game Engine API Reference","url":"/api_reference/login_reward/game_engine/"},{"content":"Models EzProbability Draw Probability Represents the calculated draw probability for a specific prize. The rate is computed from the prize’s weight relative to the total weight of all prizes in the Prize Table. For box gacha, the probability changes dynamically as prizes are drawn from the box.  prize EzDrawnPrize  Prize The prize that this probability corresponds to, including its ID and acquire actions. rate float  0 ~ 1.0 Draw Probability (0.0-1.0) The probability of drawing this prize, expressed as a value between 0.0 and 1.0. Calculated as this prize’s weight divided by the total weight of all prizes in the table. EzDrawnPrize Drawn Prize Represents a prize that has been drawn from the lottery. Contains the prize ID and the acquire actions that were executed to grant the prize to the user.  prizeId string  ~ 36 chars Prize ID The ID of the drawn prize, corresponding to a prize entry in the Prize Table. acquireActions List 0 ~ 100 items List of Acquire Actions The list of acquire actions executed to grant this prize to the user. EzBoxItems Box Items Records the state of a box gacha for a specific user and Prize Table. Contains the list of all prizes in the box along with their remaining and initial quantities, allowing the user to see which prizes have been drawn and which remain.  boxId string * ~ 1024 chars Box A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server prizeTableName string  ~ 128 chars Prize Table name The name of the Prize Table associated with this box. Identifies which box gacha this record belongs to. items List [] 0 ~ 1000 items Items The list of all prizes in the box with their remaining and initial quantities. Each item shows how many of that prize were originally in the box and how many remain, allowing tracking of the box gacha’s draw progress. EzLotteryModel Lottery Model Lottery Model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha.  name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzBoxItem Box Item Represents a single prize type within a box gacha, showing its initial quantity in the box, remaining quantity, and the acquire actions that will be executed when drawn.  prizeId string  ~ 128 chars Prize ID The ID of the prize in the Prize Table that this box item corresponds to. acquireActions List [] 0 ~ 100 items List of Acquire Actions The list of acquire actions to execute when this prize is drawn from the box. remaining int  0 ~ 2147483646 Remaining Quantity The number of this prize still remaining in the box. Decreases by one each time this prize is drawn. initial int  0 ~ 2147483646 Initial Quantity The number of this prize that was originally placed in the box. Used together with remaining to calculate how many have been drawn. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods describeBoxes Get the status of all box gachas the player has drawn from Retrieves the box state for every box-mode gacha in the namespace. Each entry shows how many of each prize have already been drawn and how many remain in the box. Use this to build an overview screen of all box gachas — for example, showing “Starter Box: 15/50 drawn” and “Premium Box: 3/100 drawn” with progress bars. This API only applies to box-mode gachas. Normal gachas don’t have box state since prizes can be drawn repeatedly without limit. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of box states nextPageToken string Page token to retrieve the rest of the listing Implementation Example getBox Get the status of a specific box gacha Retrieves the current state of a specific box by Prize Table name. The response shows each prize in the box, how many have been drawn, and how many remain. Use this to display the box gacha detail screen — for example, listing all available prizes with their remaining counts: “SSR Legendary Sword: 0/1 drawn, SR Magic Staff: 2/5 drawn, R Potion: 10/30 drawn, …” This lets the player see what’s left in the box before deciding to draw again. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name gameSession GameSession  GameSession Result Type Description item EzBoxItems Box state including prizes and their remaining quantities Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. resetBox Reset a box gacha back to its initial state Resets the box so that all prizes are returned to it, as if the player had never drawn from it. After resetting, every prize becomes available again at its original quantity. This is useful for implementing features like “Reset Box” buttons in box gacha UIs, where the player can choose to start over — typically after obtaining the main prize they wanted. For example, the player draws the SSR item from the box, then resets the box to try for another SSR in a fresh box. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name gameSession GameSession  GameSession Result Type Description item EzBoxItems Box state including prizes and their initial quantities Implementation Example listProbabilities Get the current draw probability for a gacha Retrieves the list of all prizes and their current draw probabilities for the specified gacha. Use this to display the “Draw Probability” or “Gacha Details” screen that many games show to players. The probabilities returned depend on the gacha mode: Normal gacha: The probabilities are always the same for all players (e.g., SSR: 3%, SR: 15%, R: 82%). Box gacha: The probabilities reflect the current state of the player’s box. As prizes are drawn and removed, the remaining prizes’ probabilities change accordingly. For example, if the only SSR has already been drawn, the SSR probability becomes 0%. This API is typically used to comply with gacha probability disclosure requirements. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). gameSession GameSession  GameSession Result Type Description items List List of draw probabilities Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getLotteryModel Get the details of a specific gacha/lottery Retrieves a single lottery model by name. Use this to display the gacha detail screen — showing the draw mode (normal or box), the associated Prize Table name, and other configuration. For example, before the player taps “Draw”, you can use this API to show whether the gacha is a standard gacha or a box gacha, and combine it with ListProbabilities to display the current draw probabilities. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item EzLotteryModel Lottery Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listLotteryModels Get a list of all gacha/lottery configurations Retrieves all lottery models configured in the namespace. Each model defines a gacha (lottery) — its draw mode, the Prize Table it references, and how prizes are selected. There are two draw modes: Normal: Each draw uses a fixed probability table. The same prize can be drawn any number of times. This is the standard gacha behavior. Box: Prizes are placed in a virtual box with fixed quantities. Each draw removes a prize from the box, so the same prize cannot be drawn more than its set quantity. When the box is empty, all prizes have been obtained. Use this to display a gacha list screen — for example, “Premium Gacha”, “Weapon Gacha”, “Step-Up Gacha”, etc. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Lottery Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Lottery SDK for Game Engine\n","title":"GS2-Lottery SDK for Game Engine API Reference","url":"/api_reference/lottery/game_engine/"},{"content":"Models EzGathering Gathering An entity representing a group of game players brought together by matchmaking. It has multiple parameters for matchmaking, and the players are grouped based on the totality of the parameters. Players join a Gathering by specifying their role, attributes, and optionally a blacklist of users they do not wish to play with. Joining is validated against attribute range requirements, role capacity limits, and whitelist restrictions (allowUserIds). When all role slots are filled to capacity, the Gathering is considered complete and matchmaking finishes. Gathering names are automatically generated in UUID format, and an optional expiration time can be set for automatic cleanup.  gatheringId string * ~ 1024 chars Gathering A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. capacityOfRoles List [] 1 ~ 5 items List of Role Capacities Defines the recruitment slots for this Gathering. Each entry specifies a role name, its aliases, and the maximum number of players that can fill that role. When all role slots reach their capacity, matchmaking is considered complete. At least 1, maximum 5 roles. allowUserIds List [] 0 ~ 100 items Allowed User IDs A whitelist of user IDs that are permitted to join this Gathering. When specified, only the listed users can participate in matchmaking for this Gathering. Useful for friend-only or invitation-based matchmaking scenarios. Maximum 100 entries. metadata string ~ 1024 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. expiresAt long Gathering Expiration Time The time at which this Gathering automatically expires and is deleted. If matchmaking does not complete before this time, the Gathering is cleaned up. When not specified, the Gathering persists until matchmaking completes or it is manually deleted. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzRating Rating An entity that holds the current rating value for each game player. Created automatically when a player first participates in rated matchmaking. The rating is calculated using the Glicko-2 algorithm, with an initial rate value and rating deviation (rd) that represents the uncertainty of the rating. The rate value converges toward the player’s true skill level as more matches are played.  ratingId string * ~ 1024 chars Rating A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rateValue float 1500.0 0 ~ 65535.0 Rate Value The player’s current rating score calculated by the Glicko-2 algorithm. Defaults to the initial value defined in the RatingModel (typically 1500.0). The value increases or decreases based on match results and the relative strength of opponents. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzJoinedSeasonGathering Joined Season Gathering A record that tracks which Season Gathering a player has joined within a specific season and tier. Created automatically when a player joins a Season Gathering, serving as an index to quickly look up the player’s current gathering. Each player can belong to at most one Season Gathering per season and tier combination.  seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  ~ 128 chars Season Gathering Name The name of the Season Gathering that this player has joined. Used to reference the specific Season Gathering entity within the same season and tier. EzSeasonGathering Season Gathering A persistent gathering within a season that collects players over the season period. Unlike regular Gatherings that dissolve once matchmaking completes, Season Gatherings persist throughout the season and accumulate participants. Players are grouped by tier (based on GS2-Experience rank) and season number, and each Season Gathering has a maximum participant limit defined by the SeasonModel.  seasonGatheringId string * ~ 1024 chars Season Gathering A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. name string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). participants List [] 0 ~ 1000 items List of Participant User IDs The list of user IDs of players who have joined this Season Gathering. Players are added to this list when they join and the list grows throughout the season until the maximum participant limit is reached. EzBallot Ballot A ballot paper issued to each player for reporting match results after a rated matchmaking game. Contains the context of the match: the rating model name, gathering name, and number of players. Each player receives a ballot signed by the server, which they fill in with game results and submit to the Vote API. The voting system requires more than 50% consensus among submitted ballots to finalize rating calculations.  userId string  ~ 128 chars User ID ratingName string  ~ 128 chars Rating Name The name of the RatingModel to use for rating calculations after this match. Identifies which rating system’s parameters (initial value, volatility) apply to this match’s result processing. gatheringName string  ~ 128 chars Gathering Name The name of the Gathering for which match results are being reported. Used to identify the specific matchmaking session and correlate votes from all participants in the same match. numberOfPlayer int  2 ~ 10 Number of Players The total number of players who participated in this match. Used to determine the expected number of ballots and validate consensus (more than 50% of players must submit matching results). Must be between 2 and 10. EzRatingModel Rating Model GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value.  name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. EzSeasonModel Season Model Defines the season-specific settings for Season Matchmaking, including the period of persistent gatherings, maximum participant count, and tier integration settings. Managed by GS2-Schedule for period control, and can be linked with GS2-Experience for persistent gathering within the same tier as needed.  name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management The GRN of the GS2-Experience experience model used to determine player tiers. The player’s rank within this experience model is used as their tier for matchmaking, ensuring players are grouped with others at a similar level. If not specified, tier-based grouping is disabled and all players are matched together regardless of level. challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Schedule event that defines the active period for this season. Season Gatherings can only be created and joined while this event is active. When the event period ends, the season closes and new matchmaking is no longer possible. EzPlayer Player Represents a player participating in matchmaking, containing their identity, attributes, role, and blacklist. When joining a Gathering, a Player object is created with the player’s attribute values, desired role, and a list of users they refuse to play with. The player’s attributes are validated against the Gathering’s attribute range conditions, and their deny list is cross-checked to prevent unwanted pairings.  userId string  ~ 128 chars User ID attributes List [] 0 ~ 5 items List of Attributes The player’s named numeric attributes used for matchmaking condition evaluation. Each attribute is checked against the Gathering’s AttributeRange conditions to determine eligibility. The player’s own attribute values must also fall within any range conditions they set when creating a Gathering. Maximum 5 attributes. roleName string “default” ~ 128 chars Role Name The role that this player wants to fill in the Gathering. Defaults to “default” for general matchmaking without role distinctions. For role-based matchmaking, specify the player’s specific role (e.g., “paladin”, “knight”) which is matched against role names and aliases in the Gathering’s capacity definitions. denyUserIds List [] 0 ~ 100 items Deny User IDs A blacklist of user IDs that this player refuses to be matched with. During matchmaking, if any player already in the Gathering appears in this list, the player cannot join that Gathering. Conversely, if this player is in any existing participant’s deny list, joining is also blocked. Maximum 100 entries. EzAttributeRange Attribute Range A condition that defines the acceptable range of a named attribute for joining a Gathering. When a player attempts to join, their attribute value with the matching name must fall within the specified min/max range. Used to create skill-based or level-based matchmaking filters.  name string  ~ 128 chars Attribute Name The name of the attribute to apply this range condition to. Must match the name of an attribute in the player’s attribute list for the condition to be evaluated. min int 0 0 ~ 2147483646 Minimum Attribute Value The minimum value of the attribute required to join the Gathering (inclusive). Players whose attribute value is below this threshold cannot participate. max int 0 0 ~ 2147483646 Maximum Attribute Value The maximum value of the attribute allowed to join the Gathering (inclusive). Players whose attribute value exceeds this threshold cannot participate. EzCapacityOfRole Capacity of Role Defines a recruitment slot within a Gathering for a specific role. Each role has a name, optional aliases, a maximum capacity, and a list of currently participating players. Role aliases allow flexible matching: e.g., a “tank” role with aliases “paladin” and “knight” lets players specifying either sub-role fill the tank slot. When all participants in every role reach their capacity, the Gathering’s matchmaking is complete.  roleName string “default” ~ 128 chars Role Name The name of the role for this recruitment slot. Defaults to “default” for general matchmaking without role distinctions. For role-based matchmaking (e.g., “tank”, “healer”, “attacker”), specify the role category name here. roleAliases List [] 0 ~ 9 items List of Role Name Aliases Alternative role names that are accepted for this recruitment slot. Players specifying any of these aliases as their role name will be matched into this slot. Enables sub-role matching: e.g., “paladin” and “knight” aliases for a “tank” role. Maximum 9 aliases. capacity int  1 ~ 256 Role Capacity The maximum number of players that can fill this role slot. When the number of participants reaches this capacity, the role is considered full and no more players with this role can join. Must be between 1 and 256. participants List [] 0 ~ 1000 items List of Participant Players The list of players currently occupying this role slot. Players are added when they join the Gathering and removed when they leave. Each player entry includes their user ID, attributes, role name, and blacklist. Uniqueness is enforced by user ID. EzAttribute Attribute A named numeric attribute associated with a player for matchmaking purposes. Attributes are used in conjunction with AttributeRange conditions on Gatherings to filter which players can join. For example, a “level” attribute with value 50 would match a Gathering requiring level between 40 and 60. Each player can have up to 5 attributes.  name string  ~ 128 chars Attribute Name Attribute-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). value int 0 0 ~ 2147483646 Attribute Value The numeric value of this attribute for the player. This value is checked against the min/max range specified in the Gathering’s AttributeRange conditions during matchmaking. EzGameResult Game Result Represents the result of a single player in a match, used for rating calculations via the Vote system. Each GameResult entry pairs a user ID with their rank (finishing position) in the match. Lower rank values indicate better performance (1st place = rank 1). Players with the same rank are treated as a draw.  rank int  0 ~ 2147483646 Rank The player’s finishing position in the match. 1 is the highest rank (winner). Used by the Glicko-2 algorithm to calculate rating changes: higher-ranked players gain rating while lower-ranked players lose rating. Players with equal ranks are treated as draws. userId string  ~ 128 chars User ID EzSignedBallot Signed Ballot A ballot paper with a digital signature that verifies its authenticity. The server issues signed ballots to players after matchmaking completes, ensuring that only legitimate participants can submit match results. The signature is verified when the ballot is submitted to the Vote API, preventing tampering with match context (rating name, gathering name, number of players).  body string  ~ 1024 chars Ballot Body The serialized ballot data that is the target of the digital signature. Contains the ballot context (user ID, rating name, gathering name, number of players) in a format that can be verified against the signature. signature string  ~ 256 chars Signature The digital signature used to verify the authenticity and integrity of the ballot body. Generated by the server using a GS2-Key encryption key, and verified when the ballot is submitted to prevent forgery or tampering. EzTimeSpan Time Span Represents a duration of time composed of days, hours, and minutes. Used to specify relative time offsets, such as the expiration time of a Gathering from the current time. The total duration is calculated by combining all three components.  days int 0 0 ~ 365 Days The number of days in the time span. Maximum 365 days. Defaults to 0. hours int 0 0 ~ 24 Hours The number of hours in the time span. Maximum 24 hours. Defaults to 0. minutes int 0 0 ~ 60 Minutes The number of minutes in the time span. Maximum 60 minutes. Defaults to 0. Methods cancelMatchmaking Cancel matchmaking and leave the Gathering Removes the player from the Gathering they are currently in and stops matchmaking. Use this when the player taps a “Cancel” button on the matchmaking waiting screen. Note: If matchmaking completes at the same moment the player tries to cancel, a NotFoundException (404 error) is returned because the Gathering no longer exists. Handle this case in your game — it means the match was found successfully and the player should proceed to the game instead. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. gameSession GameSession  GameSession Result Type Description item EzGathering Canceled Gathering Implementation Example createGathering Create a new room (Gathering) for matchmaking Creates a matchmaking room and starts waiting for other players to join. You define the recruitment conditions when creating a Gathering — for example, “looking for 1 attacker and 1 healer, player level must be between 10 and 20”. Key settings: capacityOfRoles: Define the roles and how many players you need for each (e.g., 2 DPS + 1 Tank + 1 Healer). attributeRanges: Set conditions for who can join based on player attributes like level or rank. allowUserIds: Restrict the Gathering to specific players (useful for friend-only or invite-only matchmaking). expiresAt: Set an expiration time for the Gathering. This is recommended — without it, old Gatherings may remain even after the player has left the game. If using expiration, prompt the player to recreate the Gathering when it expires. The player’s own user ID in the Player parameter can be omitted. After creating a Gathering, other players can find and join it by calling DoMatchmaking. When all role slots are filled, matchmaking completes and a notification is sent to all participants. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession player EzPlayer  Own player information attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. capacityOfRoles List [] 1 ~ 5 items List of Role Capacities Defines the recruitment slots for this Gathering. Each entry specifies a role name, its aliases, and the maximum number of players that can fill that role. When all role slots reach their capacity, matchmaking is considered complete. At least 1, maximum 5 roles. allowUserIds List [] 0 ~ 100 items Allowed User IDs A whitelist of user IDs that are permitted to join this Gathering. When specified, only the listed users can participate in matchmaking for this Gathering. Useful for friend-only or invitation-based matchmaking scenarios. Maximum 100 entries. expiresAt long Gathering Expiration Time The time at which this Gathering automatically expires and is deleted. If matchmaking does not complete before this time, the Gathering is cleaned up. When not specified, the Gathering persists until matchmaking completes or it is manually deleted. expiresAtTimeSpan EzTimeSpan Time to expiration Result Type Description item EzGathering Created Gathering Implementation Example doMatchmaking Search for an available Gathering and join it Searches existing Gatherings for one that matches the player’s attributes and has open slots, then joins it automatically. This is the main API for players who want to join a match rather than create one. The search takes a limited amount of time per call. If no suitable Gathering is found yet, a matchmakingContextToken is returned. Pass this token in the next call to resume the search from where it left off — keep calling in a loop until a match is found. When all Gatherings have been searched and none are available, both the Gathering and the token will be null . In this case, you should create a new Gathering with CreateGathering instead. Typical matchmaking flow: Call DoMatchmaking in a loop, passing the token each time If a Gathering is returned → matchmaking succeeded, proceed to the game If both Gathering and token are null → no matches found, create a new Gathering Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession player EzPlayer  Own player information matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state Result Type Description item EzGathering Participated Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example earlyCompleteMatchmaking Complete matchmaking early without a full party Ends matchmaking before all role slots are filled. This is useful when you want to allow the game to start with fewer players than originally requested — for example, starting a 4-player co-op dungeon with only 3 players. Only the player who created the Gathering can call this API. After calling, matchmaking is considered complete and a completion notification is sent to all participants. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. gameSession GameSession  GameSession Result Type Description item EzGathering Canceled Gathering Implementation Example getGathering Get the current state of a Gathering Retrieves the latest information about a specific Gathering, including its participants, recruitment conditions, and role capacities. Use this to display a waiting room screen — for example, “2/4 players joined, looking for: 1 Tank, 1 Healer”. You can also use this to check if matchmaking has completed by verifying that all role slots are filled. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Result Type Description item EzGathering Gathering Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. ping Send a keep-alive signal while waiting for matchmaking Notifies the server that the player is still actively waiting for matchmaking. Call this periodically while the player is on the matchmaking waiting screen. This helps the system know which players are still online and waiting. If the namespace has a timeout configured, players who don’t send a ping within the timeout period may be automatically removed from the Gathering. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Result Type Description item EzGathering Gathering updated Implementation Example updateGathering Update the recruitment conditions of a Gathering Changes the attribute range conditions of an existing Gathering that is still waiting for players. For example, if no players are joining with the condition “level 15-20”, you can broaden it to “level 10-25” to increase the pool of eligible players. Only the attribute ranges can be changed — role capacities and allowed user IDs cannot be modified after creation. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. gameSession GameSession  GameSession attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. Result Type Description item EzGathering Gathering updated Implementation Example getRatingModel Get the details of a specific rating configuration Retrieves a single rating model by name. Use this to display the rating system’s settings — including the initial rating value and volatility parameter. Higher volatility means ratings change more dramatically after each match (good for quickly calibrating new players), while lower volatility leads to more stable, gradual rating changes. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRatingModel Rating Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRatingModels Get a list of all rating configurations Retrieves all rating models configured in the namespace. Each rating model defines the parameters for a player skill rating system — for example, you might have separate ratings for “Ranked Battle”, “Arena”, and “Tournament”. GS2 uses the Glicko-2 algorithm for rating calculations. Each model specifies the initial rating value (default: 1500) and volatility (how quickly ratings change after each match). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Rating Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRating Get the player’s rating score for a specific category Retrieves the player’s current rating value for the specified rating name. Use this to display a single rating — for example, showing “Your Ranked Battle Rating: 1823” on a match result screen or lobby. The rating value goes up when the player wins and down when they lose, with the amount of change depending on the opponent’s rating and the volatility setting. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession ratingName string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRating Rating Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRatings Get the player’s rating scores across all rating categories Retrieves all of the player’s current rating values. If your game has multiple rating categories (e.g., “Ranked Battle” and “Arena”), this returns the player’s score for each one. Use this to build a profile or stats screen — for example, “Ranked Battle: 1823, Arena: 1547”. A player’s rating is automatically created when they first participate in a rated match, starting at the initial value (typically 1500). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Rating nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. createVote Create a signed ballot for reporting match results Generates a ballot (voting paper) for the player to use when reporting the outcome of a match. After a rated match ends, each player needs to report who won and who lost. This API creates a tamper-proof ballot that includes the player’s identity information and a cryptographic signature. How the match result reporting flow works: The match ends and each player’s game client calls CreateVote to get their signed ballot Each player submits their ballot along with the match results using the Vote API The server collects all votes and determines the final result by majority vote Player ratings are updated based on the confirmed result Parameters: ratingName: The name of the rating category this match belongs to (e.g., “ranked_battle”) gatheringName: The name of the Gathering (matchmaking room) where this match took place numberOfPlayer: The total number of players in the match (2-10) keyId: The encryption key used for signing the ballot (use the default key if you haven’t set up a custom one) The returned ballot body and signature are needed for the Vote or VoteMultiple API call. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. gameSession GameSession  GameSession numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot body string Data to be signed signature string Signature Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. vote Submit your match result vote Each player calls this API individually to report who won and who lost after a match. Pass the ballot body and signature obtained from CreateVote, along with the game results (a list of each player’s rank or win/loss). How voting works: After the first player votes, there is a 5-minute window for all other players to vote If all players vote before the 5 minutes, the result is confirmed immediately If some players don’t vote within 5 minutes, the result is decided by majority vote based on the votes received so far If votes are tied (e.g., 2 say “Player A won” and 2 say “Player B won”), the result is discarded and ratings are not updated (this behavior can be customized with a script) This is the simplest approach — each player votes independently. The downside is that results may take up to 5 minutes to be reflected. For instant results, use VoteMultiple instead — the winning player collects all ballots and submits them together. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ballotBody string  ~ 1024 chars Data for ballot signature targets ballotSignature string  ~ 256 chars Signature gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot Implementation Example voteMultiple Collect all ballots and submit match results at once for instant confirmation Instead of each player voting individually (which can take up to 5 minutes), the winning player collects everyone’s signed ballots and submits them all together. This confirms the result immediately. Recommended flow: The match ends — each player calls CreateVote to get their signed ballot Each player sends their ballot (body + signature) to the winning player via your game’s communication channel (e.g., the game server or peer-to-peer) The winning player calls VoteMultiple with all collected ballots and the game results The result is confirmed instantly and ratings are updated Why the winning player should collect ballots: The losing side has no reason to lie about winning (they’d gain nothing), but they might refuse to hand over their ballot Even if the losing side doesn’t cooperate, as long as you have a majority of ballots (more than half), the result will be accepted For example, in a 2v2 match, if both winners submit their ballots, that’s 2 out of 4 — enough for a majority This approach is more complex to implement but gives instant results, which is better for the player experience. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). signedBallots List 0 ~ 10 items List of Ballot with signatures gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot Implementation Example getJoinedSeasonGathering Get the Season Gathering the player joined for a specific season Retrieves the Season Gathering that the player belongs to for the specified season number. Use this to check which match group the player is in for the current season — for example, to resume showing the match lobby after the player restarts the app. If the player has not joined any Season Gathering for the specified season, or if the Gathering no longer exists, the information will not be returned. In that case, the player should start a new matchmaking search with DoSeasonMatchmaking. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzJoinedSeasonGathering JoinedSeasonGathering Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listJoinedSeasonGatherings Get a list of Season Gatherings the player has joined Retrieves all the Season Gatherings that the player is currently a member of. Use this to show a match history or active matches screen — for example, listing all the ranked matches the player is participating in or has participated in this season. You can filter by season name to show only matches for a specific ranked mode (e.g., only “Ranked 1v1” matches). This is useful for: Showing the player’s current active matches when they open the game Building a match history screen Checking if the player is already in a match before starting a new matchmaking search Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Season Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. doSeasonMatchmaking Search for an available season match and join it Searches for a Season Gathering (a persistent matchmaking group) in the player’s tier that has open slots, and joins it automatically. The player’s tier is determined by their experience level in the linked GS2-Experience model — so players of similar skill are matched together. This works similarly to regular DoMatchmaking, but with tier-based grouping: The search takes a limited amount of time per call. If no match is found yet, a matchmakingContextToken is returned. Pass this token in your next call to resume the search from where it left off. Keep calling in a loop until a match is found. When all Season Gatherings have been searched and none have open slots, both the Season Gathering and token are returned as null . Unlike regular matchmaking where you would create a new Gathering yourself, in season matchmaking a new Season Gathering is created automatically by the system when needed. Typical season matchmaking flow: Call DoSeasonMatchmaking in a loop, passing the token each time If a Season Gathering is returned → match found, proceed to the game If both are null → no available matches right now, show a “searching” screen and retry after a short delay Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state Result Type Description item EzSeasonGathering Participated Season Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example getSeasonGathering Get the current state of a Season Gathering Retrieves the details of a specific Season Gathering, including the list of participants and which tier it belongs to. Use this to display the match lobby or waiting room for a season match — for example, “Gold Tier Match #42: 3/4 players joined”. You need to specify the season number, tier, and gathering name to identify the exact Season Gathering. This information is returned when you successfully join a Season Gathering via DoSeasonMatchmaking. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSeasonGathering SeasonGathering Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSeasonModel Get the details of a specific season matchmaking configuration Retrieves a single season model by name. Use this to display the rules and settings for a specific ranked mode — for example, showing “Ranked 1v1: Max 2 players, Tier based on Arena Experience” on a mode selection screen. The response includes: maximumParticipants: How many players can be in a single match experienceModelId: Which GS2-Experience model is used to determine player tiers. The player’s experience level is mapped to a tier, and matchmaking only pairs players within the same tier. challengePeriodEventId: If set, players can only participate in ranked matches during the specified time window (e.g., weekends only, or 7PM-10PM daily) Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSeasonModel Season Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSeasonModels Get a list of all season matchmaking configurations Retrieves all season models defined in the namespace. Season matchmaking is designed for competitive games with ranked seasons — like “Season 1”, “Season 2”, etc. — where players are grouped into tiers based on their skill level. Unlike regular Gathering-based matchmaking (which creates temporary rooms), season matchmaking uses persistent groups that last for the entire season. Players in the same tier are matched together, ensuring fair competition. Each season model defines: Maximum number of participants per match The experience model used to calculate player tiers (integrates with GS2-Experience to determine skill brackets like Bronze, Silver, Gold) An optional challenge period event (integrates with GS2-Schedule to limit when matches can be played) Use this to display a list of available ranked modes — for example, “Ranked 1v1” and “Ranked 3v3”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Season Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnJoinNotification Push notification used when a new participant joins the Gathering Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. joinUserId string User ID Implementation Example OnLeaveNotification Push notification used when a participant leaves the Gathering Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. leaveUserId string User ID Implementation Example OnCompleteNotification Push notification used when matchmaking is established Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Implementation Example OnChangeRatingNotification Push notification used when rating values change Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID rateValue float Rate Value The player’s current rating score calculated by the Glicko-2 algorithm. Defaults to the initial value defined in the RatingModel (typically 1500.0). The value increases or decreases based on match results and the relative strength of opponents. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Matchmaking SDK for Game Engine\n","title":"GS2-Matchmaking SDK for Game Engine API Reference","url":"/api_reference/matchmaking/game_engine/"},{"content":"Models EzSpatial Spatial  userId string  ~ 128 chars User ID areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position EzPosition  Position vector EzVector  Vector EzAreaModel Area divides space, and different areas can be treated as different spaces even if they have the same coordinates.  name string  ~ 128 chars Area Model name 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. layerModels List [] 0 ~ 1000 items List of layer models EzLayerModel Layers allow for multiple logical hierarchies within a single space. For example, it solves the problem of an Enemy being invisible in a space with a large number of characters. Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance.  name string  ~ 128 chars Layer Model name 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. EzMyPosition My Location  position EzPosition  Position vector EzVector  Vector r float 1 0 ~ 10000 Radius EzPosition Position  x float  -1048574 ~ 1048574 X position y float  -1048574 ~ 1048574 Y position z float  -1048574 ~ 1048574 Z position EzScope Surroundings to be acquired  r float  1 ~ 16777214 Radius limit int  1 ~ 100 Maximum number of result EzVector Position  x float  -1048574 ~ 1048574 X position y float  -1048574 ~ 1048574 Y position z float  -1048574 ~ 1048574 Z position Methods describeAreaModels Get a list of Area Model Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Area Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getAreaModel Get Area Model Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description item EzAreaModel Area Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. describeLayerModels Get a list of Layer Model Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description items List List of Layer Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getLayerModel Get Layer Model Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name layerModelName string  ~ 128 chars Layer Model name Result Type Description item EzLayerModel Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. update Send position Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position EzMyPosition  My Location scopes List 0 ~ 10 items List of Scope of acquisition by other players gameSession GameSession  GameSession Result Type Description items List List of Spatial Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-MegaField SDK for Game Engine\n","title":"GS2-MegaField SDK for Game Engine API Reference","url":"/api_reference/mega_field/game_engine/"},{"content":"Models EzComplete Mission Completion Status Tracks a user’s mission completion and reward receipt status for a specific mission group. Maintains separate lists for accomplished task names and reward-received task names, distinguishing between tasks that have been completed and those whose rewards have actually been claimed.  missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. completedMissionTaskNames List [] 0 ~ 1000 items List of Completed Task Names The names of mission tasks that the user has accomplished (completion conditions met). A task appears in this list when its counter reaches the target value or verify actions pass, regardless of whether the reward has been claimed. receivedMissionTaskNames List [] 0 ~ 1000 items List of Reward received Task Names The names of mission tasks for which the user has already claimed the completion reward. A task must be in the completed list before its reward can be received. EzCounter Counter A counter is an entity that keeps track of mission progress for each game player. Counter values are aggregated by the duration of the associated task. Therefore, one counter can have multiple values. For example, for a quest clear count counter, the number of times the quest was completed this month, this week, and today. For example, a quest clear count counter could have the following values.  name string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. values List [] 0 ~ 32 items Values The list of scoped values for this counter. Each entry holds the counter value for a specific scope (reset timing or verify action condition), along with the next reset time. A single counter holds multiple values for different scopes simultaneously. EzCounterScopeModel Counter Reset Timing Model Defines a scope for a counter, which determines how and when the counter value is reset. A scope can be either a reset timing (daily, weekly, monthly, fixed-day interval, or never) or a verify action condition. Each counter can have multiple scopes to track values across different periods.  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Determines how the counter scope is defined. “resetTiming” uses a periodic reset schedule, while “verifyAction” uses a verify action to determine whether the counter value applies. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the counter value for this scope is reset. Choose from: not reset (permanent cumulative), daily, weekly, monthly, or every fixed number of days. Only used when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the counter value resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the counter value resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the counter value resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name A unique name that identifies this verify action condition scope. Used to look up the corresponding scoped value in the counter. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” condition EzVerifyAction {scopeType} == “verifyAction”  Condition The verify action that determines whether the counter value for this scope is applicable. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between counter value resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” EzCounterModel Counter Model Counter Model is an entity that can be set as a condition for accomplishing mission tasks. Since counter values can be referenced by multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions.  name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Specifies the GS2-Schedule event that defines the time window during which this counter can be incremented or decremented. If not set, the counter can be operated at any time. EzMissionGroupModel Mission Group Model A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission.  name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. tasks List [] 0 ~ 1000 items List of Mission Task The mission tasks belonging to this group. Each task defines a completion condition (counter threshold or verify actions) and the rewards granted upon accomplishment. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. EzMissionTaskModel Mission Task Model A mission task is an entity that defines the conditions under which a reward will be given if the value of the associated counter exceeds a certain level.  name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter EzTargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” * [] 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received Specifies the GS2-Schedule event that defines the time window during which the mission task rewards can be claimed. If not set, rewards can be received at any time after accomplishment. premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. EzTargetCounterModel Target Counter Information about the counter that serves as the achievement goal for the mission  counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Specifies which type of counter scope to use for the mission completion check. “resetTiming” evaluates the counter value for a specific reset period, while “verifyAction” evaluates the value for a named condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming” * Target Reset timing Specifies which reset timing scope of the counter to check against the target value. For example, selecting “daily” means the task checks the daily counter value. If omitted, the mission group’s reset timing is used. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Enabled only if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition scope to check against the target value. Must match a conditionName defined in the counter model’s scopes. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long  0 ~ 9223372036854775805 Target value The threshold value that the counter’s scoped value must reach or exceed for the mission task to be considered accomplished. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzScopedValue Scoped Value Represents a counter value within a specific scope. Each scoped value holds the accumulated count for a particular reset timing (e.g., daily, weekly, monthly) or verify action condition. When the reset timing arrives, the value is reset to zero. The counter value has an upper bound and will not exceed the maximum value even when incremented.  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Indicates whether this scoped value is based on a reset timing schedule or a verify action condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming”  Reset timing The reset timing for this scoped value. Determines the period over which the counter value is accumulated before being reset. Only applicable when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Required if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition that this scoped value corresponds to. Used to identify which condition scope this value belongs to. Only applicable when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long 0 0 ~ 9223372036854775805 Count value The accumulated counter value for this scope. Increases when the counter is incremented and decreases when decremented. The value is capped at the maximum and will not go below zero. EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods batchReceiveRewards Claim rewards for multiple completed missions at once Claims the rewards for multiple mission tasks within the same group in a single call. This is the “Claim All” button in your mission UI — instead of the player tapping “Claim” on each mission one by one, they can claim everything at once. All specified tasks must be completed and not yet received. The rewards for all tasks are combined into a single transaction. For example, if the player has completed “Win 3 battles” (reward: 50 Gems) and “Collect 500 gold” (reward: 1 Gacha Ticket), calling this with both task names gives the player 50 Gems + 1 Gacha Ticket in one operation. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskNames List  1 ~ 100 items Task name list gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example evaluateComplete Re-evaluate mission completion status Re-checks all counter values against mission task conditions within the specified group and updates the completion status. Normally, mission completion is checked automatically every time a counter is increased. However, if you add new mission tasks to an existing group after counters have already been incremented, those new tasks won’t be automatically evaluated. Call this API in that situation to retroactively check if the player’s existing counter values already meet the new tasks’ conditions. For example: You add a new daily mission “Win 1 battle” to a group. Players who already won battles today already have the counter value to complete it, but the system doesn’t know yet. Calling EvaluateComplete will check and mark it as completed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. gameSession GameSession  GameSession Result Type Description item EzComplete Completion Status updated Implementation Example getComplete Get the player’s completion status for a specific mission group Retrieves which mission tasks the player has completed and which rewards have been claimed within the specified mission group. Use this to display the mission list screen for a specific group — for example, showing each daily mission with its status: “Win 3 battles” — Completed, reward claimed (checkmark) “Collect 500 gold” — Completed, reward available! (claim button) “Use 10 items” — In progress: 7/10 (progress bar) Combine with ListMissionTaskModels or GetMissionGroupModel to get the task definitions (objectives, thresholds, rewards), and with GetCounter to get the current counter values for showing progress bars. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. gameSession GameSession  GameSession Result Type Description item EzComplete Completion Statuses Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCompletes Get the player’s mission completion status across all groups Retrieves the completion and reward claim status for all mission groups. Each entry shows which mission tasks the player has completed (met the counter threshold) and which rewards have already been claimed. Use this to build an overview mission screen — for example, showing badges or notification dots on groups that have unclaimed rewards: “Daily Missions (2 rewards available!)”, “Weekly Missions (complete)”, “Achievements (1 new!)” A mission task has two states: Completed: The counter met the threshold (e.g., “Win 5 battles” and the player has won 5 or more) Received: The player has claimed the reward for the completed task A task that is “completed but not received” means the player has earned the reward but hasn’t claimed it yet — this is what you should highlight in the UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Completion Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. receiveRewards Claim the reward for a completed mission Claims the reward for a specific mission task that the player has completed. The task must be completed (counter threshold met) and not yet received. When called, the configured reward is given to the player — for example, 100 Gems, a Gacha Ticket, or 500 Gold. This is the “Claim” or “Receive” button in your mission UI. The typical flow is: The player sees a completed mission with an available reward The player taps the “Claim” button Your game calls ReceiveRewards The reward is given and the task is marked as “received” If the task is not yet completed or the reward has already been claimed, an error is returned. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name Task-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example deleteCounter Delete a counter completely Deletes the specified counter and all its scope values for the player. Unlike ResetCounter (which resets only specific scopes), this removes the entire counter as if the player had never had any progress. Use this when you want to completely clear a player’s progress for a specific counter — for example, when implementing a full mission reset feature. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. Result Type Description item EzCounter Counter deleted Implementation Example getCounter Get the player’s value for a specific counter Retrieves the current value of a specific counter for the player, including all scope values. For example, if the counter is “battle_wins”, the response might include: daily=3, weekly=12, total=87. Use this to show mission progress for a specific objective — for example, displaying a progress bar “3/5 battles won today” next to a daily mission. Each scope value represents the counter tracked over a different time period, allowing you to show both short-term and long-term progress. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. Result Type Description item EzCounter Counter Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCounters Get the player’s current counter values Retrieves all counter values for the player. Each counter tracks a specific player action (like battle wins, items collected, or gold earned) and contains values for each scope (daily, weekly, monthly, all-time). Use this to build an overview of the player’s mission progress — for example, showing “Battles won today: 3” or “Total quests completed: 42” on a stats or mission screen. Counter values are automatically increased when the player performs actions in the game (via reward actions from other services), and are automatically checked against mission task thresholds. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. resetCounter Reset specific scopes of a counter Resets the counter values for the specified scopes only. For example, you can reset just the daily scope of a counter without affecting the weekly or all-time values. This is useful when you want to manually reset a specific period’s progress — for instance, resetting a “daily challenge” counter when the player uses a special item to retry daily missions. Only the scoped values matching the specified scope types are reset; all other scoped values remain unchanged. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. scopes List  1 ~ 20 items List of scopes Result Type Description item EzCounter Counter deleted Implementation Example getCounterModel Get the details of a specific counter definition Retrieves a single counter model by name, including its scopes and reset conditions. Use this to understand what a counter tracks and how its values are managed — for example, to show the player what actions contribute to a mission’s progress. The response includes the list of scopes defined for this counter, each with its reset type (daily, weekly, monthly, or none) and reset timing. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzCounterModel Counter Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCounterModels Get a list of all counter definitions Retrieves all counter models defined in the namespace. Counters are the values that track player actions and drive mission completion. For example, a “battle_wins” counter tracks how many battles the player has won, and a “gold_collected” counter tracks total gold earned. Each counter model defines one or more “scopes” — these determine how the counter value is tracked across different time periods: A counter can simultaneously track daily, weekly, monthly, and all-time values For example, a “battle_wins” counter might have: today’s wins (daily scope), this week’s wins (weekly scope), and total wins (all-time scope) Different mission tasks can reference different scopes of the same counter (e.g., “Win 3 battles today” uses the daily scope, while “Win 100 battles total” uses the all-time scope) Counter values are typically increased automatically as a reward action from other GS2 services (e.g., when completing a quest or purchasing an item), but can also be increased manually from your game server. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Counter Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getMissionGroupModel Get the details of a specific mission group Retrieves a single mission group by name, including its reset type, reset timing settings, and the list of mission tasks it contains. Use this to display the mission list within a specific group — for example, when the player taps on the “Daily Missions” tab, call this to get all the daily mission tasks and their details. The response includes the mission tasks defined in the group, each with their target counter condition and reward configuration. Combine this with GetComplete to show the player’s progress and completion status for each task. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzMissionGroupModel Mission Group Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listMissionGroupModels Get a list of all mission groups Retrieves all mission groups defined in the namespace. Mission groups are categories that organize individual missions together — for example, “Daily Missions”, “Weekly Missions”, “Story Missions”, or “Achievement Missions”. Each group has a reset type that determines when the missions in the group reset: notReset: Missions never reset (permanent achievements like “Clear Stage 10” or “Collect 100 characters”) daily: Missions reset every day (e.g., “Win 3 battles today”) weekly: Missions reset every week (e.g., “Log in 5 days this week”) monthly: Missions reset every month (e.g., “Spend 10,000 gold this month”) Use this to build the main mission list screen — for example, showing tabs for “Daily”, “Weekly”, and “Achievement” categories. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Mission Group Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getMissionTaskModel Get the details of a specific mission task Retrieves a single mission task by name within the specified mission group. Use this to display the detail screen for a specific mission — showing the objective, current progress, reward, and whether it’s completed. The response includes: The target counter name and threshold (what the player needs to achieve) The reward actions (what the player receives upon claiming) Any prerequisite task (a task that must be completed first) The verification type for completion checking Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzMissionTaskModel Mission Task Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listMissionTaskModels Get a list of all mission tasks in a group Retrieves all individual mission tasks within the specified mission group. Each mission task represents a single mission objective — for example, “Win 5 battles”, “Collect 1,000 gold”, or “Clear Stage 3”. Each task defines: A target counter and a threshold value (e.g., counter “battle_wins” \u003e= 5) Rewards given when the player claims the completed mission (e.g., 100 Gems) Optional prerequisite tasks (e.g., “Win 10 battles” only appears after “Win 5 battles” is completed) The mission system works automatically: When the player does something in the game (wins a battle, collects gold, etc.), the corresponding counter is increased The system checks if the counter value meets any task’s threshold If it does, the task is marked as “completed” The player can then claim the reward using ReceiveRewards Use this to display the mission list with objectives and rewards for each task in a group. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Mission Task Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnCompleteNotification Push notification used when mission tasks are accomplished Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). groupName string Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string User ID taskName string Mission Task Name Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Mission SDK for Game Engine\n","title":"GS2-Mission SDK for Game Engine API Reference","url":"/api_reference/mission/game_engine/"},{"content":"Models EzWallet Wallet Currency in the wallet is managed separately for currency purchased for a fee and currency obtained for free. Currency purchased for a fee is further managed by the unit price at the time of purchase, allowing for refunds in the event of service termination, or to determine if the balance is sufficient to meet the requirements of the Funds Settlement Act. The wallet has slots and each slot has a different balance. If balances cannot be shared across platforms, they can be managed separately by using different slots for each platform. Currency acquired for free can also be shared across all platforms.  slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. paid int 0 0 ~ 2147483646 Paid Currency Amount The total amount of paid (purchased) currency in this wallet slot. This is the sum of all WalletDetail entries with a non-zero unit price. Increased by deposits from store purchases, decreased by withdrawals according to the consumption priority. free int 0 0 ~ 2147483646 Free Currency Amount The total amount of free (granted) currency in this wallet slot. This corresponds to the WalletDetail entry with unit price of 0. When shareFree is enabled on the namespace, this value is synchronized from slot 0 across all wallet slots. shareFree bool false Share Free Currency Whether free currency in this wallet is shared across all slots. This value is inherited from the namespace setting at wallet creation time. When true, free currency is synchronized from slot 0 to all other wallet slots. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server Methods get Get the player’s premium currency wallet balance Retrieves the player’s wallet for the specified slot, showing the current balance of both paid and free premium currency. “Paid” currency is what the player purchased with real money (e.g., bought 100 Gems for $0.99), while “free” currency is earned through gameplay (e.g., event rewards, login bonuses). These are tracked separately because some features may require paid currency only (e.g., certain gacha or special offers). Use this to display the player’s currency balance — for example, “Gems: 350 (Paid: 100, Free: 250)” on the shop or header UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. Result Type Description item EzWallet Wallet Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. withdraw Spend premium currency from the player’s wallet Deducts the specified amount of premium currency from the player’s wallet. By default (paidOnly = false), free currency is spent first, then paid currency is used for the remainder. This ensures players use up free currency before dipping into purchased currency. If paidOnly is set to true, only paid currency is consumed — this is required for features that legally must use paid currency only (e.g., paid-only gacha in some regions). Use this when the player makes a purchase using premium currency — for example, spending 100 Gems to buy a special item or pull a gacha. Note: if currency is consumed as a cost for purchasing products via GS2-Showcase, the consumption is handled automatically — you don’t need to call this API for those cases. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. count int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency Result Type Description item EzWallet Post-withdraw Wallet price float Price of currency consumed 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 ConflictException ConflictException The wallet operation process conflicted. Retry required. InsufficientException BadRequestException Wallet balance is insufficient. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Money SDK for Game Engine\n","title":"GS2-Money SDK for Game Engine API Reference","url":"/api_reference/money/game_engine/"},{"content":"Models EzWallet Wallet Currency in the wallet is managed separately for currency purchased for a fee and currency obtained for free. Currency purchased for a fee is further managed by the unit price at the time of purchase, allowing for refunds in the event of service termination, or to determine if the balance is sufficient to meet the requirements of the Funds Settlement Act. The wallet has slots and each slot has a different balance. If balances cannot be shared across platforms, they can be managed separately by using different slots for each platform. Currency acquired for free can also be shared across all platforms.  slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. summary EzWalletSummary  Wallet Status A summary of the wallet’s current balance, broken down into paid currency, free currency, and total amounts. Calculated from the deposit transactions. sharedFreeCurrency bool  Share free currency Indicates whether the free currency in this wallet is shared across all slots. Inherited from the namespace setting at wallet creation time. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzSubscribeTransaction Subscription purchase information Represents a subscription purchase record from a store platform. Tracks the detailed subscription status through its lifecycle including active, trial, intro offer, grace period, canceled, expired, and revoked states. Each transaction is linked to a specific store platform and user.  contentName string  ~ 128 chars Store Subscription Content Model name store string (enum) enum {   “AppleAppStore”,   “GooglePlay”,   “fake” }  Store The store platform where the purchase was made. Determines which verification method is used for receipt validation. Definition Description “AppleAppStore” Apple App Store “GooglePlay” Google Play “fake” Fake transactionId string  ~ 1024 chars Transaction ID The unique transaction identifier assigned by the store platform. Used to prevent duplicate processing of the same purchase. statusDetail string (enum) enum {   “active@active”,   “active@converted_from_trial”,   “active@in_trial”,   “active@in_intro_offer”,   “grace@canceled”,   “grace@grace_period”,   “grace@on_hold”,   “inactive@expired”,   “inactive@revoked” }  Status The detailed subscription status. Prefixed with the simplified category (active/grace/inactive) followed by the specific state. Active states indicate the subscription is usable; grace states indicate payment issues but temporary access; inactive states indicate the subscription is no longer valid. Definition Description “active@active” Active “active@converted_from_trial” Converted from free trial to paid plan “active@in_trial” In free trial “active@in_intro_offer” In introductory offer “grace@canceled” User has manually canceled “grace@grace_period” The payment failed, but it is within the grace period. “grace@on_hold” Payment has failed. If payment is not completed within a specified period, the service will be unavailable. “inactive@expired” Subscription has expired “inactive@revoked” Subscription has been revoked expiresAt long  Expiration time The timestamp at which this subscription transaction expires. Updated when the subscription is renewed by the store platform. EzSubscriptionStatus Subscription status Tracks a user’s subscription contract status for a specific subscription content. Provides a simplified active/inactive status derived from the detailed subscription transaction states, along with the expiration time and the list of associated subscription transactions.  contentName string  ~ 128 chars Store Subscription Content Model name userId string ~ 128 chars User ID status string (enum) enum {   “active”,   “inactive” }  Status The simplified subscription status. “active” includes active, trial, intro offer, and grace period states. “inactive” includes expired and revoked states. Definition Description “active” Active “inactive” Inactive expiresAt long  Expiration time The timestamp at which the subscription expires. Updated when the subscription is renewed or its status changes. detail List [] 0 ~ 100 items Subscription status details The list of subscription transactions associated with this subscription. Each transaction represents a purchase record from a store platform with detailed status information (active, trial, grace period, expired, revoked, etc.). EzStoreContentModel Store Content Model This is a model for storing content from various store platforms.  name string  ~ 128 chars Store Content Model name metadata string ~ 1024 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. appleAppStore EzAppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay EzGooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. EzWalletSummary Wallet Status A summary view of a wallet’s currency balance, separating paid and free amounts. Calculated by aggregating all deposit transactions in the wallet based on their price (paid if price \u003e 0, free if price = 0).  paid int 0 0 ~ 2147483646 Count of paid currency The total amount of currency that was purchased with real money (deposit transactions with price \u003e 0). free int 0 0 ~ 2147483646 Count of free currency The total amount of currency obtained for free (deposit transactions with price = 0), such as login bonuses or event rewards. total int 0 0 ~ 2147483646 Total The total currency balance (paid + free). Represents the overall available amount in the wallet. EzDepositTransaction Deposit Transaction Represents a single deposit record in the wallet. Paid deposits (price \u003e 0) are tracked per unit price to enable accurate refund calculations and compliance with the Funds Settlement Act. Free deposits (price = 0) are tracked separately. When withdrawing, deposit transactions are consumed based on the namespace’s currency usage priority.  price double  0.0 ~ 100000000.0 Purchase Price The real-money price paid for this deposit in the local currency. A value of 0 indicates free currency. Used to calculate per-unit cost for refund purposes. currency string {price} \u003e 0  ~ 8 chars Currency Code The ISO currency code (e.g., “JPY”, “USD”) of the real-money payment. Only applicable for paid deposits (price \u003e 0). * Required if price is greater than 0 count int  0 ~ 2147483646 Quantity of premium currency The number of virtual currency units in this deposit. Decreases as currency is withdrawn from the wallet. EzAppleAppStoreContent Content of Apple AppStore Contains the Apple App Store product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Apple App Store product identifier registered in App Store Connect for this in-app purchase item. EzGooglePlayContent Content of Google Play Contains the Google Play product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Google Play product identifier registered in Google Play Console for this in-app purchase item. EzAppleAppStoreSubscriptionContent Subscription content of Apple AppStore Contains the Apple App Store subscription group identifier for subscription-based products. Used to manage and verify auto-renewable subscriptions.  subscriptionGroupIdentifier string ~ 64 chars Subscription Group ID The subscription group identifier registered in App Store Connect. Subscriptions within the same group are mutually exclusive, meaning a user can only subscribe to one at a time. EzGooglePlaySubscriptionContent Google Play Subscription Content Contains the Google Play product ID for subscription-based products. Used to manage and verify auto-renewable subscriptions on Google Play.  productId string ~ 1024 chars Product ID Methods get Get the player’s premium currency wallet balance Retrieves the player’s wallet for the specified slot, showing the current balance of both paid and free premium currency. “Paid” currency is what the player purchased with real money (e.g., bought 100 Gems for $0.99), while “free” currency is earned through gameplay (e.g., event rewards, login bonuses). These are tracked separately because some features may require paid currency only (e.g., certain gacha or special offers). Use this to display the player’s currency balance — for example, “Gems: 350 (Paid: 100, Free: 250)” on the shop or header UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. Result Type Description item EzWallet Wallet Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. list Get a list of the player’s premium currency wallets Retrieves all wallets the player currently has. Each wallet manages its own balance, with paid and free currency tracked separately. “Paid” currency is what the player purchased with real money (e.g., bought 100 Gems for $0.99), while “free” currency is earned through gameplay (e.g., event rewards, login bonuses). Use this to display the player’s full currency overview — for example, a currency management screen showing all wallet slots and their balances. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Wallets nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. withdraw Spend premium currency from the player’s wallet Deducts the specified amount of premium currency from the player’s wallet. By default (paidOnly = false), free currency is spent first, then paid currency is used for the remainder. This ensures players use up free currency before dipping into purchased currency. If paidOnly is set to true, only paid currency is consumed — this is required for features that legally must use paid currency only (e.g., paid-only gacha in some regions). Use this when the player makes a purchase using premium currency — for example, spending 100 Gems to buy a special item or pull a gacha. Note: if currency is consumed as a cost for purchasing products via GS2-Showcase, the consumption is handled automatically — you don’t need to call this API for those cases. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency Result Type Description item EzWallet Post-withdraw Wallet withdrawTransactions List List of consumed deposit transactions 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 ConflictException ConflictException The wallet operation process conflicted. Retry required. InsufficientException BadRequestException Wallet balance is insufficient. Implementation Example allocateSubscriptionStatus Register a subscription using a store receipt Links a subscription purchase to the player by verifying the receipt from the App Store or Google Play. After a player purchases a subscription (e.g., “Monthly Pass”) on their device, pass the store receipt to this API to activate the subscription on the server side. This is the essential step to connect the store purchase to the player’s account — without calling this, the server won’t know the player has subscribed. Use this in the purchase flow — for example, after the player buys a “Monthly Pass” in the in-app purchase dialog, send the receipt to activate VIP benefits. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession receipt string  ~ 1024 chars Receipt Result Type Description item EzSubscriptionStatus Subscription status 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 AlreadyUsedException BadRequestException The subscription contract for that period has already been used by another user. Implementation Example getSubscriptionStatus Get a specific subscription status Retrieves the subscription status for a specific content by name. The status shows whether the player is currently subscribed and related details such as expiration timing. Use this to check if the player has a specific subscription — for example, checking if the “Monthly Pass” is active before granting daily bonus rewards, or displaying “VIP Membership: Active” on the player’s profile. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession contentName string  ~ 128 chars Store Subscription Content Model name Result Type Description item EzSubscriptionStatus Subscription status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSubscriptionStatuses Get a list of the player’s subscription statuses Retrieves the subscription statuses for all subscription content that the player may have. A subscription is a recurring purchase like a “Monthly Pass” or “VIP Membership” from the App Store or Google Play. Each status shows whether the player is currently subscribed to that content. Use this to display a subscription overview — for example, showing “Monthly Pass: Active (expires March 15)” and “VIP Membership: Not subscribed” on a membership screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession Result Type Description items List List of Subscription statuses Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. takeOverSubscriptionStatus Transfer a subscription from another account to this player Moves a subscription that is currently linked to a different player account to this player’s account. This is used when a player migrates their account — for example, if a player switches devices and creates a new account, they can transfer their existing “Monthly Pass” subscription from the old account to the new one using the store receipt. The subscription is unlinked from the old account and linked to the new account, so the old account will no longer have the subscription benefits. Use this in the account migration flow — for example, after the player logs in to their new account and confirms the transfer. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession GameSession receipt string  ~ 1024 chars Receipt Result Type Description item EzSubscriptionStatus Subscription status 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 LockPeriodNotElapsedException BadRequestException The lock period has not elapsed since the last user change. Implementation Example Event Handlers OnChangeSubscriptionStatus Push notification when the subscription status of the period changes Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string User ID contentName string Store Subscription Content Model name Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Money2 SDK for Game Engine\n","title":"GS2-Money2 SDK for Game Engine API Reference","url":"/api_reference/money2/game_engine/"},{"content":"Models EzNews News Article Represents a single news article generated from Hugo site data. Each article belongs to a section and content path, and has a title, timestamp, and front matter metadata. Articles can optionally be linked to a GS2-Schedule event to control their display period. The front matter contains additional metadata in JSON format, including an optional weight field for controlling display order.  section string  ~ 1024 chars Section Name The section (category) to which this article belongs, corresponding to the Hugo content directory structure. Used to organize articles into logical groups for display. content string  ~ 1024 chars Content The content path identifier for this article within its section. Together with the section, uniquely identifies the article’s location in the Hugo content structure. title string  ~ 1024 chars Article Headline The title of the news article, typically defined in the Hugo front matter. Displayed as the headline when listing articles for the player. scheduleEventId string ~ 1024 chars GS2-Schedule Event A unique resource name assigned to all information handled by GS2\" \u003e GRN timestamp long  Timestamp Unix time, milliseconds frontMatter string  ~ 1024 chars Front Matter Metadata associated with the article in JSON format, originally defined in the Hugo markdown front matter. May contain arbitrary fields such as weight (for controlling display order), tags, categories, and other custom properties. EzSetCookieRequestEntry Set Cookie Request Entry Represents a cookie key-value pair that must be set in the browser/WebView to access the news article web content. The client must set these cookies before loading the article URLs to ensure authorized access to the content.  key string  ~ 128 chars Cookie Key The name of the cookie that must be set for authenticated access to the news content. Maximum 128 characters. value string  ~ 1024 chars Cookie Value The value of the cookie that must be set for authenticated access to the news content. Maximum 1024 characters. Methods getContentsUrl Get the URL and cookies needed to display news content Retrieves the information required to display news articles in a WebView or browser. News content is hosted as web pages, so to display them you need: (1) cookies for authentication, and (2) the URL to open. The response includes a browser URL (requires cookies to be set first) and a ZIP URL (for downloading all content without cookies — useful for offline or custom rendering). Use this before opening a news article — for example, call this API, set the returned cookies in the WebView, then navigate to the browser URL to show the article. Alternatively, download the ZIP to render the content natively in your game UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of cookies that need to be set in order to access the content browserUrl string URL to access the content zipUrl string URL to access the announcement contents in ZIP format (Cookie setting is not required for access) Implementation Example listNewses Get a list of news articles Retrieves the list of in-game news articles (announcements) for the player. News articles are HTML-based web content managed through GS2 — for example, maintenance notices, event announcements, update patch notes, and campaign information. The response also includes hash values for cache validation, so you can check if the content has changed since the last fetch. Use this to build an in-game news/announcements screen — for example, showing a list of articles like “Maintenance on March 1st”, “New Event: Spring Festival”, “Version 2.5 Update Notes”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of News Articles contentHash string Hash value of News Article data templateHash string Hash value of template data Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-News SDK for Game Engine\n","title":"GS2-News SDK for Game Engine API Reference","url":"/api_reference/news/game_engine/"},{"content":"Models EzProgress Quest Progress It is created at the beginning of the quest and deleted at the end. When you exit the application in the middle of an in-game, this data will remain. It is possible to resume the game from the ongoing quest information maintained by the entity.  progressId string * ~ 1024 chars Quest Progress A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server transactionId string  UUID ~ 36 chars Transaction ID Unique identifier for the quest transaction. Used to associate the quest progress with the transaction that manages reward distribution. questModelId string  ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN GRN of the quest model currently in progress. Identifies which quest the user is playing, enabling game resume if the application is closed mid-quest. randomSeed long  0 ~ 9223372036854775805 Random Seed Random number seed assigned at quest start. Used to determine the content variation (reward set) selected for this quest attempt, ensuring reproducible results. metadata string ~ 256 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. rewards List [] 0 ~ 1000 items Completion Rewards List of rewards to be granted upon successful quest completion. Determined at quest start based on the content variation selected by the random seed. failedRewards List [] 0 ~ 1000 items Failed Rewards List of rewards to be granted when the quest fails. Determined at quest start, providing consolation rewards or partial cost refunds upon failure. EzCompletedQuestList Completed Quest List Tracks the quests a user has completed within a quest group. Used to determine prerequisite quest completion and first-clear bonus eligibility. Each quest name is recorded only once regardless of how many times it is cleared.  questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. completeQuestNames List [] 0 ~ 1000 items Completed Quest Names List of quest names that the user has completed within this quest group. Quest names are added upon first completion and are deduplicated. Used to evaluate prerequisite quest conditions and first-clear bonus eligibility. EzQuestGroupModel Quest Group Model A Quest Group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups.  name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. quests List [] 0 ~ 1000 items Quests belonging to the group List of quest models that belong to this quest group. Only one quest within the group can be in progress at a time. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. EzQuestModel Quest Model A Quest Model is an entity that defines the cost required to start a quest and the rewards obtained upon completion. The reward obtained upon completion of the quest can have multiple variations and can be drawn at the start of the quest. For example, the same content can be used to manage the clear flag of a quest, but two types of content can be prepared based on whether or not a rare monster appears.  questModelId string * ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. contents List [] 1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. EzContents Contents Represents one variation of quest content. Each quest can have multiple content variations with different rewards, and one is selected by weighted random draw at quest start. The metadata supports template variable substitution with user ID and config values.  metadata string ~ 256 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. completeAcquireActions List [] 0 ~ 10 items Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. EzConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzReward Reward Represents a single reward item determined at quest start. Contains the acquire action to execute, the target resource, and the quantity to grant. Stored in the Progress entity and used to distribute rewards upon quest completion or failure.  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 request string  ~ 5242880 chars Request JSON string of the request parameters used when executing the acquire action. Contains the specific details of the reward, such as target namespace, resource name, and quantity. itemId string  ~ 1024 chars Item ID GRN of the resource to be acquired as a reward. Identifies the specific item, currency, or other resource that will be granted to the player. value int  0 ~ 2147483646 Value The quantity of the resource to be granted as a reward. This value can be adjusted dynamically based on game logic. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods deleteProgress Cancel the player’s current quest Deletes the player’s quest in progress, allowing them to start a different quest. Use this when the player wants to abandon a quest — for example, showing a “Give up this quest?” confirmation dialog, and calling this API when they confirm. This is an alternative to using the force option when starting a new quest. Use this when you want to give the player an explicit “abandon quest” button rather than silently discarding the previous quest. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzProgress Quest Progress Implementation Example end Report quest completion or failure Tells the server that the player has finished playing the quest. You need to report two things: isComplete : Whether the player cleared the quest (true) or failed (false). rewards : The actual rewards the player earned during the quest. These must not exceed the maximum values received when the quest started. If the player cleared the quest (isComplete = true), the reported rewards are granted to the player (e.g., items added to inventory, currency added to wallet). If the player failed (isComplete = false), the rewards parameter is ignored and the failure rewards configured in the quest definition are granted instead. The server validates the reported rewards — if you report more than the allowed maximum or items that don’t exist in this quest, an error occurs. Use this when the quest gameplay ends — for example, after the player beats the boss or the “Game Over” screen appears. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession rewards List [] 0 ~ 1000 items The actual rewards from the quest isComplete bool  Whether the quest has been completed config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzProgress Quest Progress transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example getProgress Get the player’s current quest progress Retrieves the quest that the player is currently playing, along with the quest group and quest definition details. This is useful for resuming a quest after the app is restarted — for example, if the player was in the middle of “Stage 1-3” and closed the app, you can call this on launch to detect the unfinished quest and show a “Resume Quest?” dialog. If the player has no quest in progress, no progress data is returned. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzProgress Quest Progress questGroup EzQuestGroupModel Quest Group Model quest EzQuestModel Quest Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. start Start a quest Tells the server that the player is starting a quest. The player can only have one quest in progress per quest group — if another quest is already running, this will fail (use force = true to discard the previous quest and start a new one). When the quest starts successfully, the response includes: The maximum rewards available in this quest (e.g., “up to 3 Swords, up to 100 Gold”). Use this to determine what the player can earn during gameplay. A random number seed for reproducible gameplay. By using this seed, the game can be replayed under the same conditions — helpful for debugging or resuming after a crash. A transaction ID that uniquely identifies this quest run. You’ll need this when reporting the quest result. Use this when the player taps “Start” on a quest — for example, starting “Stage 1-3” in the “Chapter 1” group. The quest costs (like stamina) are automatically consumed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name questName string  ~ 128 chars Quest Model name gameSession GameSession  GameSession force bool false If have a quest already started, you can discard it and start it config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result 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 InProgressException BadRequestException Quest is already underway. Implementation Example describeCompletedQuestLists Get a list of the player’s completed quest records Retrieves the player’s cleared quest records for all quest groups. Each entry corresponds to one quest group and contains a list of quest names that the player has successfully completed within that group. Use this to build a quest progress overview — for example, showing “Chapter 1: 5/10 cleared”, “Chapter 2: 0/8 cleared”, “Event Dungeon: 3/3 cleared” on a quest selection screen. This information is also useful for determining which quests are unlocked, since some quests require clearing specific previous quests as a prerequisite. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Completed Quest lists nextPageToken string Page token to retrieve the rest of the listing Implementation Example getCompletedQuestList Get the player’s completed quest record for a specific group Retrieves the list of quest names that the player has cleared within the specified quest group. Use this to check which quests in a specific group the player has already completed — for example, showing cleared/uncleared status for each stage in “Chapter 1”, or checking if the player has cleared the prerequisite quest to unlock the next stage. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. gameSession GameSession  GameSession Result Type Description item EzCompletedQuestList Completed Quest List Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getQuestGroup Get a specific quest group definition by name Retrieves a single quest group by specifying its name. The returned information includes the list of quests in the group and optional challenge period settings (e.g., event dungeons that are only available during certain time periods). Use this to display the details of a specific quest category — for example, showing all stages in “Chapter 1” or all available quests in the “Event Dungeon” category. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzQuestGroupModel Quest Group Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listQuestGroups Get a list of quest group definitions Retrieves all quest groups registered in this namespace. A quest group is a category that organizes related quests together — for example, “Chapter 1”, “Event Dungeon”, or “Daily Quests”. Players can only have one quest in progress per group, so groups also serve as a way to manage concurrent quest limits. Use this to build a quest selection screen — for example, showing categories like “Main Story”, “Side Quests”, “Event Dungeons” for the player to choose from. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Quest Group Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getQuest Get a specific quest definition by name Retrieves a single quest by specifying the group name and quest name. The returned information includes the quest’s reward settings, consume actions (costs to start), and prerequisite quest conditions. Use this to display the details of a specific quest before the player starts it — for example, showing “Stage 1-3: Rewards: Sword x1, Gold x100 | Cost: Stamina x10 | Requires: Clear Stage 1-2” on a quest detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questName string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzQuestModel Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listQuests Get a list of quest definitions in a group Retrieves all quests that belong to the specified quest group. Each quest defines its rewards (what the player can earn), costs (items or currency consumed to start), and prerequisites (quests that must be cleared first). Use this to display the quest list within a category — for example, showing “Stage 1-1”, “Stage 1-2”, “Stage 1-3 (locked — clear 1-2 first)” inside the “Chapter 1” group. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Quest Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Quest SDK for Game Engine\n","title":"GS2-Quest SDK for Game Engine API Reference","url":"/api_reference/quest/game_engine/"},{"content":"Models EzScore Score Holds the registered scores for each game player per category. Each score entry is identified by a unique ID and associated with a category and scorer user. In sum mode, new scores are added to the existing total via the AddScore operation rather than creating separate entries. Scores outside the category’s minimum/maximum range are rejected at registration.  categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID uniqueId string  UUID ~ 36 chars Unique ID A UUID that uniquely identifies this score entry. Automatically generated on creation. Used to distinguish multiple score entries from the same user in the same category when uniqueByUserId is disabled. scorerUserId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value registered by the player. Must be within the category’s configured minimum/maximum range. In sum mode, this value can be incremented via the AddScore operation. metadata string ~ 512 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. EzRanking Ranking Represents a single entry in a ranking leaderboard, containing the user’s rank, score, and associated metadata. There are two types: global ranking (all players compete on a shared board with batch calculation) and scope ranking (per-user boards based on subscribed players with real-time reflection). Rankings are sorted by the category’s configured order direction, and entries with the same score share the same rank while maintaining distinct indices.  rank long  1 ~ 9223372036854775805 Rank The ranking position of this entry, starting from 1. Entries with the same score share the same rank value. For example, if two users tie for 1st place, both have rank 1 and the next entry has rank 3. index long  0 ~ 9223372036854775805 Index A zero-based sequential index within the ranking list. Unlike rank, the index is always unique and sequential even when multiple entries share the same score. Used for pagination and range-based queries. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. metadata string ~ 512 chars Metadata Arbitrary metadata associated with this ranking entry. Inherited from the score registration and returned alongside ranking results. Maximum 512 characters. createdAt long  Creation Timestamp Unix time, milliseconds * Automatically configured on the server EzSubscribeUser Subscribe User Represents an individual subscription relationship within a scope ranking category. Each entry indicates that the parent user is subscribed to (following) the target user’s scores in the specified category.  userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Target User ID The user ID of the player being subscribed to. This user’s scores will appear in the subscribing user’s scope ranking for the specified category. EzCategoryModel Category Model Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting EzGlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. EzGlobalRankingSetting Global Ranking Setting Global is a ranking where all players see the same results. The ranking interval can be set from 15 minutes to 24 hours. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  calculateIntervalMinutes int  15 ~ 1440 Calculate Interval Minutes The interval in minutes between successive ranking recalculations. The system periodically recalculates the global ranking based on all registered scores at this interval. Range: 15 to 1440 minutes (15 minutes to 24 hours). additionalScopes List 0 ~ 10 items Additional Scopes A list of additional time-windowed aggregation scopes. Each scope defines a separate ranking that only considers scores registered within a specified number of days. This enables creating daily, weekly, or monthly leaderboards alongside the all-time global ranking. Maximum 10 scopes. EzScope Aggregation Scope Defines an additional time-windowed aggregation scope for Global Ranking mode. Normally, global ranking is calculated for all registered scores regardless of when they were submitted. By adding scopes, you can create separate rankings that only consider scores registered within a specified number of days, enabling daily, weekly, or monthly leaderboards alongside the all-time ranking.  name string  ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. targetDays long  1 ~ 365 Target Days The number of days to include in the aggregation window. Only scores registered within this number of days from the current time are considered for the scoped ranking. Range: 1-365 days. Methods getCategory Get the details of a specific ranking category Retrieves a single ranking category by name, including its scoring rules and configuration. The response includes: Score range: The minimum and maximum allowed score values Sort order: Whether higher scores rank better (descending) or lower scores rank better (ascending, useful for time attack rankings) Scope type: Whether it’s a global ranking or a scoped (friend) ranking For global rankings: The calculation interval and timing settings Entry/access period: If linked to GS2-Schedule events, when players can submit scores and view rankings Use this to display ranking rules or settings on a detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzCategoryModel Category Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listCategories Get a list of all ranking categories Retrieves all ranking categories defined in the namespace. Each category represents a separate leaderboard — for example, “High Score”, “Boss Time Attack”, “Weekly Battle Wins”, etc. There are two types of rankings: Global ranking: All players are ranked together on a single leaderboard. Rankings are recalculated periodically (not in real-time), so there is a delay between submitting a score and seeing it reflected in the rankings. Scoped ranking: Each player sees a personalized leaderboard showing only themselves and the players they have subscribed to (like a “Friend Ranking”). This is calculated in real-time. Use this to display the list of available leaderboards on your ranking screen — for example, tabs for “World Ranking”, “Friend Ranking”, “Weekly Ranking”, etc. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSubscribes Get the list of players you are following for friend ranking Retrieves the list of players that the current player has subscribed to (is following) for the specified ranking category. This is used with scoped (friend) rankings — when you subscribe to another player, their scores appear in your personalized friend ranking. Use this to display a “Following” list on the ranking screen, showing which players’ scores are included in the friend leaderboard. For example, if the player has subscribed to PlayerA, PlayerB, and PlayerC, the friend ranking will show scores from these three players plus the player themselves. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name gameSession GameSession  GameSession Result Type Description items List List of Subscribed User Information Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. subscribe Follow a player to include them in your friend ranking Subscribes to another player so that their scores appear in your scoped (friend) ranking for the specified category. This is like a “Follow” feature — after subscribing, the target player’s scores will be visible in your personalized friend leaderboard. Common use cases: When the player adds someone as a friend, automatically subscribe to them for all ranking categories On a player profile screen, provide a “Follow on Leaderboard” button After a match, let the player follow opponents they played against You cannot subscribe to yourself (your own score is always included in your friend ranking automatically). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name gameSession GameSession  GameSession targetUserId string  ~ 128 chars Target User ID Result Type Description item EzSubscribeUser Subscribed User Information Implementation Example unsubscribe Unfollow a player and remove them from your friend ranking Removes the subscription to the specified player for the specified ranking category. After unsubscribing, the target player’s scores will no longer appear in your scoped (friend) ranking. Use this when the player wants to stop seeing someone’s scores in their friend leaderboard — for example, when removing a friend or unfollowing a player. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name gameSession GameSession  GameSession targetUserId string  ~ 128 chars Target User ID Result Type Description item EzSubscribeUser Unsubscribed Subscribed User Information Implementation Example getNearRanking Get rankings around a specific score Retrieves a portion of the ranking centered on the specified score value. This is useful for showing the player “where they would rank” — for example, displaying a few players above and below the player’s score on the leaderboard. Typical use case: After the player finishes a game, show them their score and the nearby rankings: “98th: PlayerX (5,200 pts) → You: 5,150 pts → 99th: PlayerY (5,100 pts)” This API is only available for global rankings. For scoped (friend) rankings, use GetRanking instead since the list is small enough to display entirely. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. Result Type Description items List List of Ranking Scores Implementation Example getRank Get a specific player’s rank and score Retrieves the ranking information for a specific player, including their rank position and score. Use this to show “Your Rank: 42nd (8,500 pts)” on a result screen or profile page. You need to specify the scorerUserId (the player whose rank you want to look up). The uniqueId can be omitted (defaults to “0”) if the category only allows one score per player. If the category allows multiple scores per player, specify the uniqueId to identify which score to look up. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. scorerUserId string  ~ 128 chars User ID of the user who earned the score gameSession GameSession  GameSession uniqueId string “0” ~ 36 chars Score Unique ID Result Type Description item EzRanking Ranking Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRanking Get the ranking leaderboard Retrieves the ranking list for the specified category, showing players ordered by their score. This is the main API for displaying a leaderboard screen — for example, “1st: PlayerA (10,500 pts), 2nd: PlayerB (9,800 pts), …”. You can specify a startIndex to begin from a specific rank position (e.g., startIndex=0 for the top, startIndex=99 for ranks around 100th place). For global rankings, the data is based on the last calculation, so there may be a delay between score submission and ranking updates. For scoped (friend) rankings, the data is calculated in real-time. If the category supports additional scopes, you can specify additionalScopeName to filter the ranking further. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. gameSession GameSession GameSession limit int 30 1 ~ 1000 Number of data items to retrieve pageToken string ~ 4096 chars Token specifying the position from which to start acquiring data startIndex long 0 ~ 9223372036854775805 Index to start retrieving rankings Result Type Description items List List of Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. putScore Submit a score to the ranking Registers the player’s score in the specified ranking category. Call this when the player achieves a score you want to record — for example, after completing a stage, finishing a time attack, or at the end of a match. You can optionally attach metadata to the score (as a string). This is useful for storing extra display information like the player’s character name, team composition, or replay data — anything you want to show alongside the score on the leaderboard. How the score is used depends on the category type: Global ranking: The score is collected and the ranking is recalculated at the next scheduled interval. There is a delay before the ranking is updated. Scoped ranking: The score is reflected immediately and appears in the friend rankings of players who have subscribed to this player. Note: Depending on the category settings, only the highest score (or lowest for ascending rankings) may be kept per player, or multiple scores may be allowed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. metadata string ~ 512 chars Metadata Arbitrary metadata associated with this ranking entry. Inherited from the score registration and returned alongside ranking results. Maximum 512 characters. Result Type Description item EzScore Registered Scores Implementation Example getScore Get a specific score submitted by a player Retrieves a single score record for the specified player in the specified ranking category. Use this to display the details of a specific score — for example, showing the score value, submission time, and any attached metadata (like character name or replay data). The uniqueId identifies which score to retrieve when a player has multiple scores. If the category only allows one score per player (the most common case), you can omit the uniqueId or set it to “0”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name gameSession GameSession  GameSession scorerUserId string  ~ 128 chars User ID uniqueId string “0” ~ 36 chars Score Unique ID Result Type Description item EzScore Score Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listScores Get a list of scores submitted by a specific player Retrieves all scores that a specific player has submitted in the specified ranking category. Use this to show a player’s score history — for example, listing all their attempts at a time attack stage. This is different from viewing the ranking (which shows all players sorted by score). This API focuses on one specific player’s submitted scores. If the category only allows one score per player, this will return a single entry. If the category allows multiple scores (e.g., multiple attempts), this returns all of them. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name scorerUserId string  ~ 128 chars User ID gameSession GameSession  GameSession limit int 30 1 ~ 1000 Number of data items to retrieve pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data Result Type Description items List List of Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Ranking SDK for Game Engine\n","title":"GS2-Ranking SDK for Game Engine API Reference","url":"/api_reference/ranking/game_engine/"},{"content":"Models EzGlobalRankingData Global Ranking Represents a ranked entry in the global ranking for a specific season. Contains the user’s score, 0-based index (sorted position), and 1-based rank (which accounts for ties). The rank is calculated as index + 1.  rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. userId string  ~ 128 chars User ID index int 0 ~ 2147483646 Index The 0-based unique sorted position of this entry in the ranking. Unlike rank, index is always unique even when scores are tied. Used for index-based reward calculation. rank int 0 ~ 2147483646 Rank The 1-based ranking position. Players with the same score share the same rank. Calculated as index + 1. Used for rank-based reward calculation. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzGlobalRankingReceivedReward Global Ranking Reward Received History It is possible to set rewards for global ranking positions. To set rewards, set the ranking threshold and reward details.  rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. userId string  ~ 128 chars User ID receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzGlobalRankingScore Global Ranking Score Stores a user’s submitted score for a global ranking in a specific season. When the sum mode is enabled, multiple submitted scores are accumulated.  rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzClusterRankingData Cluster Ranking Represents a ranked entry in a cluster ranking for a specific season and cluster. Contains the user’s score, 0-based index, and 1-based rank within the cluster.  rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID index int 0 ~ 2147483646 Index The 0-based unique sorted position within the cluster ranking. Always unique even when scores are tied. rank int 0 ~ 2147483646 Rank The 1-based ranking position within the cluster. Players with the same score share the same rank. Calculated as index + 1. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzClusterRankingReceivedReward Cluster Ranking Reward Received History You can set rewards according to the cluster ranking. To set rewards, set the ranking threshold and reward details.  rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server EzClusterRankingScore Cluster Ranking Score Stores a user’s submitted score for a cluster ranking in a specific season and cluster. The user’s cluster membership is verified based on the cluster type setting before the score is accepted.  rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzSubscribeRankingData Subscribe Ranking Represents a ranked entry in a user’s personalized subscribe ranking for a specific season. Contains scores from subscribed users, ranked among the user’s friend list. Each entry includes the scorer’s user ID to identify who achieved the score.  rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. scorerUserId string  ~ 128 chars Scorer User ID The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend’s score this entry represents. index int 0 ~ 2147483646 Index The 0-based unique sorted position within the subscribe ranking. rank int 0 ~ 2147483646 Rank The 1-based ranking position within the subscribe ranking. Calculated as index + 1. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzSubscribeRankingScore Subscribe Ranking Score Stores a user’s submitted score for a subscribe ranking in a specific season. This score is visible to users who have subscribed to this user, forming their personalized friend ranking.  rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server EzSubscribeUser Subscribed User Information Represents a subscription relationship between two users for the subscribe ranking.  rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Subscribe Target User ID The user ID of the player being subscribed to. This player’s scores will be included in the subscriber’s personalized ranking. EzGlobalRankingModel Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  globalRankingModelId string * ~ 1024 chars Global Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. rankingRewards List {entryPeriodEventId} != null * [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. EzClusterRankingModel Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  clusterRankingModelId string * ~ 1024 chars Cluster Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering rankingRewards List {entryPeriodEventId} != null * [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. EzSubscribeRankingModel Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking.  subscribeRankingModelId string * ~ 1024 chars Subscribe Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. EzRankingReward Ranking Reward Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.  thresholdRank int  1 ~ 1001 Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). metadata string ~ 1024 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. acquireActions List [] 0 ~ 100 items List of Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getGlobalRankingRank Get the player’s own rank in a global ranking Retrieves the player’s own ranking entry, including their rank position and score. Use this to display the player’s position on the leaderboard — for example, showing “Your rank: #42 (15,000 pts)” at the top of the ranking screen, or “You are ranked #42 out of 10,000 players”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzGlobalRankingData Global Ranking Implementation Example listGlobalRankings Get the global ranking leaderboard Retrieves the global ranking leaderboard entries, showing players ranked by their scores. Each entry includes the player’s user ID, score, rank position, and any attached metadata. Use this to display the leaderboard — for example, showing “1st: Alice (25,000 pts), 2nd: Bob (22,500 pts), 3rd: Charlie (20,000 pts)” on a ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Global Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getGlobalRankingModel Get a specific global ranking definition by name Retrieves a single global ranking model by specifying its name. The returned information includes the score range, sort order, reward settings, and season/entry period configurations. Use this to display the rules of a specific ranking — for example, showing “High Score Ranking — Resets monthly, Top 100 get rewards, Higher score = better rank” on a ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzGlobalRankingModel Global Ranking Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGlobalRankingModels Get a list of global ranking definitions Retrieves all global ranking models registered in this namespace. A global ranking is a leaderboard where all players in the game compete against each other — for example, “World High Score”, “Arena Rating”, or “Total Damage Ranking”. Each model defines the ranking rules: score range, sort order (ascending or descending), season schedule, and ranking rewards. Use this to see what global rankings exist — for example, to display a “Leaderboards” menu showing “High Score Ranking”, “Speed Clear Ranking”, “PvP Rating” as options. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Global Ranking Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getGlobalRankingReceivedReward Check if the player has claimed a specific global ranking reward Retrieves the reward claim record for a specific global ranking and season. Use this to check if the player has already claimed the reward for a specific ranking season — for example, showing a “Claim Reward” button if unclaimed, or “Already Claimed” if already received. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzGlobalRankingReceivedReward Global Ranking Reward Received History Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGlobalRankingReceivedRewards Get a list of the player’s global ranking reward claim history Retrieves the player’s history of claimed ranking rewards from global rankings. Each entry shows which ranking and season the reward was claimed for, allowing you to check which rewards have already been collected. Use this to display reward claim status — for example, showing “High Score Ranking Season 1: Claimed, Season 2: Claimed, Season 3: Not yet claimed” on a ranking rewards screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Global Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. receiveGlobalRankingReward Claim the global ranking reward Claims the ranking reward based on the player’s final rank in the specified global ranking and season. The reward is determined by the player’s rank position and the ranking model’s reward settings — for example, top 10 players might receive a special item, while top 100 receive gems. The reward items are automatically granted to the player. Use this when the player taps “Claim Reward” on the ranking results screen after a season ends. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzGlobalRankingModel Global Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example getGlobalRankingScore Get the player’s submitted score for a specific global ranking Retrieves the player’s score for a specific global ranking and season. Use this to display the player’s current score on a specific leaderboard — for example, showing “Your score: 15,000 pts (Season 3)” on the ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzGlobalRankingScore Global Ranking Score Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listGlobalRankingScores Get a list of the player’s submitted scores for global rankings Retrieves all scores the player has submitted to global rankings. Each score entry shows which ranking it was submitted to and the score value. Use this to display the player’s own scores — for example, showing “Your High Scores: Stage Clear: 15,000 pts, Arena: 2,400 pts” on a profile or ranking overview screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Global Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. putGlobalRanking Submit a score to a global ranking Registers the player’s score to the specified global ranking. You can also attach metadata (e.g., a replay ID or character name used). If the player has already submitted a score, this updates it based on the ranking’s rules (e.g., keep the highest score, or always use the latest). Use this after the player completes a scored activity — for example, after clearing a stage, submit the clear time or score to the “High Score Ranking”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. metadata string ~ 512 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. Result Type Description item EzGlobalRankingScore Registered Global Ranking Score Implementation Example getClusterRankingRank Get the player’s own rank in a cluster ranking Retrieves the player’s own ranking entry within a specific cluster (group), including their rank position and score. Use this to display the player’s position within their group — for example, showing “Your guild rank: #3 (8,500 pts)” at the top of the guild ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzClusterRankingData Cluster Ranking Implementation Example listClusterRankings Get the cluster ranking leaderboard Retrieves the leaderboard entries for a specific cluster (group), showing players ranked by their scores within that group. Each entry includes the player’s user ID, score, rank position, and any attached metadata. Use this to display the group leaderboard — for example, showing the guild ranking “1st: Alice (8,500 pts), 2nd: Bob (7,200 pts), 3rd: Charlie (6,800 pts)” on a guild ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Cluster Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getClusterRankingModel Get a specific cluster ranking definition by name Retrieves a single cluster ranking model by specifying its name. The returned information includes the score range, sort order, cluster type, reward settings, and season/entry period configurations. Use this to display the rules of a specific cluster ranking — for example, showing “Guild DPS Ranking — Weekly reset, compete within your guild, Top 10 get rewards” on a ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzClusterRankingModel Cluster Ranking Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listClusterRankingModels Get a list of cluster ranking definitions Retrieves all cluster ranking models registered in this namespace. A cluster ranking is a leaderboard within a specific group (cluster) — for example, rankings within a guild, a region, or a game server. Unlike global rankings where all players compete together, cluster rankings let players compete within their group, which is useful for guild-based events or regional competitions. Use this to see what cluster rankings exist — for example, to display “Guild DPS Ranking”, “Regional Score Ranking” as options on a ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Cluster Ranking Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getClusterRankingReceivedReward Check if the player has claimed a specific cluster ranking reward Retrieves the reward claim record for a specific cluster ranking, cluster, and season. Use this to check if the player has already claimed the reward — for example, showing a “Claim Reward” button if unclaimed, or “Already Claimed” if already received, on a guild ranking results screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzClusterRankingReceivedReward Cluster Ranking Reward Received History Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listClusterRankingReceivedRewards Get a list of the player’s cluster ranking reward claim history Retrieves the player’s history of claimed ranking rewards from cluster rankings. Each entry shows which ranking, cluster, and season the reward was claimed for. Use this to display reward claim status for group rankings — for example, showing “Guild DPS Ranking Season 1: Claimed, Season 2: Not yet claimed” on a guild ranking rewards screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Cluster Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. receiveClusterRankingReward Claim the cluster ranking reward Claims the ranking reward based on the player’s final rank in the specified cluster ranking, cluster, and season. The reward is determined by the player’s rank position within their group and the ranking model’s reward settings — for example, the top player in each guild might receive a special guild champion item. The reward items are automatically granted to the player. Use this when the player taps “Claim Reward” on the group ranking results screen after a season ends. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzClusterRankingModel Cluster Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example getClusterRankingScore Get the player’s submitted score for a specific cluster ranking Retrieves the player’s score for a specific cluster ranking, cluster, and season. Use this to display the player’s current score within their group — for example, showing “Your score in Dragon Slayers guild: 8,500 pts (Season 2)” on a guild ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzClusterRankingScore Cluster Ranking Score Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listClusterRankingScores Get a list of the player’s submitted scores for cluster rankings Retrieves the player’s scores submitted to a specific cluster ranking within a specific cluster (group). Use this to display the player’s own scores within their group — for example, showing “Your Guild DPS Score: 8,500 pts” on a guild ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Cluster Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. putClusterRanking Submit a score to a cluster ranking Registers the player’s score to the specified cluster ranking within a specific cluster (group). You can also attach metadata. The cluster name identifies which group the score belongs to — for example, the guild name for a guild ranking. Use this after the player completes a scored activity within their group — for example, after clearing a guild raid boss, submit the DPS score to the “Guild DPS Ranking” for the player’s guild. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. gameSession GameSession  GameSession score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. metadata string ~ 512 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. Result Type Description item EzClusterRankingScore Registered Cluster Ranking Score Implementation Example getSubscribe Check if the player is following a specific user for subscribe rankings Retrieves the subscription information for a specific target user. Use this to check if the player is already following a particular user — for example, showing a “Following” or “Follow” button on another player’s profile, or verifying the subscription before displaying their score on the friend leaderboard. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetUserId string  ~ 128 chars Subscribe Target User ID Result Type Description item EzSubscribeUser Subscribed User Information Implementation Example listSubscribes Get a list of users the player is following for subscribe rankings Retrieves all users that the player has subscribed to (followed) for subscribe rankings. Subscribe rankings only show scores from followed users, so this list determines who appears on the player’s friend leaderboard. Use this to display the player’s “following” list for rankings — for example, showing “Following: Alice, Bob, Charlie” on a friend ranking management screen, or to check how many friends the player is tracking. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Subscribed User Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSubscribeRankingRank Get the player’s own rank in a subscribe (friend) ranking Retrieves the player’s own ranking entry among their friends, including their rank position and score. Use this to display the player’s position on the friend leaderboard — for example, showing “Your rank among friends: #2 (10,500 pts)” at the top of the friend ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzSubscribeRankingData Subscribe Ranking Implementation Example listSubscribeRankings Get the subscribe (friend) ranking leaderboard Retrieves the friend leaderboard, showing only scores from users the player has subscribed to (followed). Each entry includes the user ID, score, rank position, and any attached metadata. Use this to display the friend leaderboard — for example, showing “1st: Alice (12,000 pts), 2nd: You (10,500 pts), 3rd: Bob (9,800 pts)” on a friend ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession 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 List of Subscribe Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSubscribeRankingModel Get a specific subscribe ranking definition by name Retrieves a single subscribe ranking model by specifying its name. The returned information includes the score range, sort order, and season/entry period configurations. Use this to display the rules of a specific subscribe ranking — for example, showing “Friends High Score — Weekly reset, Higher score = better rank” on a ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSubscribeRankingModel Subscribe Ranking Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSubscribeRankingModels Get a list of subscribe ranking definitions Retrieves all subscribe ranking models registered in this namespace. A subscribe ranking is a friends-only leaderboard — the player only sees scores from users they have subscribed to (followed). This is perfect for friend competitions — for example, “Friends High Score” or “Friends Weekly Challenge” where players compete only against their friends rather than all players in the game. Use this to see what subscribe rankings exist — for example, to display “Friends High Score”, “Friends Speed Clear” as options on a friend ranking screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Subscribe Ranking Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getSubscribeRankingScore Get the player’s submitted score for a specific subscribe ranking Retrieves the player’s score for a specific subscribe (friend) ranking and season. Use this to display the player’s current score in a specific friend ranking — for example, showing “Your score: 12,000 pts (This week)” on the friend ranking detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season gameSession GameSession  GameSession Result Type Description item EzSubscribeRankingScore Subscribe Ranking Score Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSubscribeRankingScores Get a list of the player’s submitted scores for subscribe rankings Retrieves all scores the player has submitted to subscribe (friend) rankings. Use this to display the player’s own scores in friend rankings — for example, showing “Your Friends High Score: 12,000 pts” on a friend ranking overview screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Subscribe Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. putSubscribeRanking Submit a score to a subscribe ranking Registers the player’s score to the specified subscribe (friend) ranking. You can also attach metadata. This score will appear on the friend leaderboards of all users who have subscribed to (followed) this player. Use this after the player completes a scored activity — for example, after clearing a stage, submit the score to the “Friends High Score” ranking so the player’s friends can see it. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. Result Type Description item EzSubscribeRankingScore Registered Subscribe Ranking Score Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Ranking2 SDK for Game Engine\n","title":"GS2-Ranking2 SDK for Game Engine API Reference","url":"/api_reference/ranking2/game_engine/"},{"content":"Models EzRoom Room Represents a dedicated game server instance for handling real-time communication in multiplayer matches. Room creation is asynchronous: after the request, the system provisions a server and assigns an IP address, port, and encryption key once the instance is ready. Clients should wait for the create notification (or poll) before attempting to connect. The encryption key is used to establish a secure communication channel between the game clients and the relay server.  name string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ipAddress string ~ 128 chars IP Address The IP address of the provisioned game server. Assigned automatically by the system after the room’s server instance is ready. Not available immediately after room creation. Maximum 128 characters. port int 0 ~ 65535 Port The listening port number of the provisioned game server. Assigned automatically along with the IP address after the server instance is ready. Range: 0-65535. encryptionKey string ~ 256 chars Encryption Key The encryption key for securing communication between game clients and the relay server. Assigned automatically along with the IP address and port after the server instance is ready. Clients must use this key to encrypt/decrypt messages sent through the relay server. Maximum 256 characters. Methods now Get the current server time Returns the current time on the GS2 server as a Unix timestamp in milliseconds. Use this to synchronize the game client’s clock with the server — for example, to accurately display countdown timers, event start/end times, or cooldown periods. Since the client device’s clock can be wrong or manipulated, using the server time ensures all players see consistent timing. Common use cases: Calculate the time offset between client and server at game startup, then apply it throughout the session Display accurate “time remaining” for limited-time events or ranking periods Validate timing-sensitive actions on the client side before sending them to the server Request  Result Type Description timestamp long Current time Unix time, milliseconds Implementation Example getRoom Get the connection details for a real-time game room Retrieves the information needed to connect to a real-time game server room, including the IP address, port number, and encryption key. Real-time rooms are used for multiplayer gameplay that requires low-latency communication — for example, action games, fighting games, or co-op dungeon runs. The typical flow for using real-time rooms: A player requests room creation (this is done through a separate API and is processed asynchronously) When the room is ready, participating players receive a push notification Each player calls GetRoom to get the connection details (IP address, port, encryption key) The game client connects to the room server using these details and starts real-time communication The encryption key is used to secure communication between the client and the game server. Each room has a unique key. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzRoom Room Information Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. Event Handlers OnCreateNotification Push notification used when room creation is complete Name Type Description namespaceName string Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Realtime SDK for Game Engine\n","title":"GS2-Realtime SDK for Game Engine API Reference","url":"/api_reference/realtime/game_engine/"},{"content":"Models EzTrigger Trigger Defines the starting point for relative event scheduling, enabling per-player event periods. When a trigger is activated for a player, it records the activation time (triggeredAt) and an expiration time (expiresAt). Events configured with “relative” schedule type reference a trigger by name; the event period for that player starts from the trigger’s activation time and ends at its expiration. Triggers can be renewed (resetting createdAt and updating expiresAt) and are automatically cleaned up via TTL after expiration.  triggerId string * ~ 1024 chars Trigger A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server expiresAt long  Expires At The timestamp when this trigger expires and the relative event period ends. After this time, the trigger is considered expired (IsExpire returns true) and the associated relative event is no longer active for this player. The trigger data is automatically cleaned up via DynamoDB TTL after expiration. Expressed as Unix time in milliseconds. EzEvent Event Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period.  name string  ~ 128 chars Event name Event-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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” EzRepeatSchedule Repeat Schedule Represents the current state of an event’s repeat cycle at a given point in time. Contains the repeat count (how many times the cycle has occurred), the current active window’s start and end times, the last completed window’s end time, and the next upcoming window’s start time. This information is computed dynamically from the event’s repeat settings and the current time.  repeatCount int  0 ~ 2147483646 Repeat Count The number of repeat cycles that have completed up to the current time. Increments each time a repeat window ends. Useful for tracking progress through seasonal or periodic event cycles. currentRepeatStartAt long Current Repeat Start At The start time of the currently active repeat window. Null if the event is not currently in an active repeat window. Expressed as Unix time in milliseconds. currentRepeatEndAt long Current Repeat End At The end time of the currently active repeat window. Null if the event is not currently in an active repeat window. Expressed as Unix time in milliseconds. lastRepeatEndAt long Last Repeat End At The end time of the most recently completed repeat window. Null if no repeat window has ended yet. Expressed as Unix time in milliseconds. nextRepeatStartAt long Next Repeat Start At The start time of the next upcoming repeat window. Null if there are no more upcoming repeat windows within the event period. Expressed as Unix time in milliseconds. Methods getTrigger Get a specific trigger’s status Retrieves a specific trigger by name, showing when it was activated and when it expires. Use this to check the status of a specific trigger — for example, checking if the “first_login” trigger is still active and how much time remains before it expires, in order to display a countdown for the associated event like “Beginner Bonus ends in 3 days 12 hours”. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzTrigger Trigger Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listTriggers Get a list of the player’s active triggers Retrieves all triggers that are currently active for the player. A trigger is a player-specific timer used to activate relative schedule events. When a trigger is “pulled” (activated), it starts a countdown and any events linked to that trigger become active for the player. For example, a “first_login” trigger might activate a “7-Day Beginner Bonus” event, or a “first_purchase” trigger might activate a “24-Hour Thank You Sale” event. Each trigger has an expiration time — once it expires, the associated events also end for that player. Use this to see which triggers are currently active for the player — for example, to display “Beginner Bonus: Active (expires in 5 days)” on a status screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Triggers nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getEvent Get a specific event’s schedule status Retrieves a specific event by name, along with its current schedule status for the player. The response includes whether the event is currently active (inSchedule), the start and end times, and repeat schedule information if applicable. For relative schedule events, the end time is calculated based on the player’s trigger — so different players may have different end times for the same event. Use this to check if a specific event is running and display its remaining time — for example, showing “Summer Event: 3 days remaining” or “Beginner Bonus: Ends in 12 hours” with a countdown timer. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description item EzEvent Event inSchedule bool Whether in schedule scheduleStartAt long Schedule start time scheduleEndAt long Schedule end time If the event type is absolute, the absoluteEnd of the EventModel is stored. If the event type is relative, scheduleEndAt stores either the trigger’s expiration time or the absoluteEnd of the EventModel, whichever ends sooner. repeatSchedule EzRepeatSchedule Repeat Schedule isGlobalSchedule bool Is the event a global schedule Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listEvents Get a list of currently active events for the player Retrieves all events that are currently running for this player. There are two types of events: Absolute schedule events: fixed date/time events that are the same for all players (e.g., “Christmas Event: Dec 24 - Dec 25”, “Summer Sale: Jul 1 - Jul 31”) Relative schedule events: per-player events that start when a trigger is activated (e.g., “7-Day Beginner Bonus” starting from the player’s first login, “24-Hour Flash Sale” starting from when the player reaches level 10) Only events that are currently in their active period are returned. Use this to show the player what events are happening right now — for example, displaying active event banners on the home screen or enabling event-specific UI elements. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession Result Type Description items List List of Events Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way.","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Schedule SDK for Game Engine\n","title":"GS2-Schedule SDK for Game Engine API Reference","url":"/api_reference/schedule/game_engine/"},{"content":"Models EzBallot Ballot A voting ticket issued to each player for a specific match session. Contains the match context (season, session, number of players) and the player’s user ID. The ballot is signed by the server and returned to the player, who then fills in game results and submits it back as part of a WrittenBallot. During vote aggregation, ballots from all participants are compared via majority consensus to prevent result manipulation.  userId string  ~ 128 chars User ID seasonName string  ~ 128 chars Season Name The name of the season model used for this match’s rating calculations. References the SeasonModel that defines the tier structure and point adjustment rules applied to this match. sessionName string  ~ 128 chars Session Name The name of the match session this ballot belongs to. All ballots within the same session are aggregated together during the voting process. numberOfPlayer int  2 ~ 10 Number of Players The total number of participants in this match. Determines when the vote is considered complete: all ballots must be collected (or majority achieved) before results are finalized. Valid range: 2 to 10. EzSeasonModel Season Model Defines the tier structure and point adjustment rules applied during a season. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience.  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. EzTierModel Tier Model TierModel defines the point adjustment rules for each tier within a season. Specifies point change ranges by rank, entry fees, and promotion bonuses. While actual point data is managed by GS2-Experience, the calculation logic for point adjustments is determined by the TierModel configuration.  metadata string ~ 128 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. raiseRankBonus int  0 ~ 10000 Raise Rank Bonus Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion. For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold. Valid range: 0 to 10000. minimumChangePoint int  -99999999 ~ -1 Minimum Change Point The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss. Must be a negative value. The actual point change for a losing player falls between this value and 0. Valid range: -99999999 to -1. maximumChangePoint int  1 ~ 99999999 Maximum Change Point The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win. Must be a positive value. The actual point change for a winning player falls between 0 and this value. Valid range: 1 to 99999999. EzGameResult Match Result Represents the outcome of a single player in a match. Contains the player’s user ID and their finishing rank. Used within a WrittenBallot to report the results of all participants. During vote aggregation, game results are compared across all submitted ballots using majority consensus to determine the official outcome.  rank int  0 ~ 2147483646 Rank The finishing position of this player in the match. 1 indicates first place (winner). The rank value is used to determine point adjustments based on the TierModel configuration. userId string  ~ 128 chars User ID EzSignedBallot Signed Ballot A ballot that has been cryptographically signed by the server using GS2-Key. The signature ensures that the ballot content (season, session, player, number of participants) has not been tampered with. When submitting a vote, the signed ballot is verified server-side before the game results are accepted.  body string  ~ 1024 chars Body The serialized JSON representation of the ballot data that serves as the signature target. Contains the ballot content (user ID, season name, session name, number of players) in a format that can be verified against the signature. Maximum 1024 characters. signature string  ~ 256 chars Signature The cryptographic signature generated by GS2-Key for the ballot body. Used to verify that the ballot was issued by the server and has not been modified by the client. Base64-encoded, maximum 256 characters. EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getSeasonModel Get the details of a specific season rating definition Retrieves a single season model by name, including its tier configuration and rules. The response includes: Tier definitions: The list of rating tiers (e.g., Bronze at 0 points, Silver at 1000 points, Gold at 2500 points) with bonus points awarded on rank-up Experience model reference: Which GS2-Experience model is used to store and manage rating values Challenge period event: If linked to a GS2-Schedule event, when the competitive season is active and players can participate in rated matches Use this to display season details on a ranked play screen — for example, showing the player’s current tier, the points needed for the next tier, and whether the season is currently active. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzSeasonModel Season Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listSeasonModels Get a list of all season rating definitions Retrieves all season models defined in the namespace. Each season model represents a separate competitive rating system — for example, “Ranked Battle Season 1”, “Arena Rating”, or “Tournament Rating”. Season rating is a system where players compete in matches and their rating goes up or down based on wins and losses. Ratings are stored using GS2-Experience, which means rating values behave like experience points — they can increase, decrease, and trigger rank-ups (e.g., Bronze → Silver → Gold). Each season model defines: Rating tiers (e.g., Bronze, Silver, Gold, Platinum) with thresholds for promotion Which GS2-Experience model stores the rating values Optionally, a GS2-Schedule event that controls when the competitive season is active (challenge period) Use this to display a list of available competitive modes on your game’s ranked play screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Season Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. createVote Create a signed ballot for reporting match results Generates a signed ballot that the player will use to report the outcome of a match. This is the first step in the match result reporting flow — each player who participated in the match must create their own ballot. The complete flow for reporting match results: The match ends and each player’s game client calls CreateVote to get a signed ballot Each player submits their ballot along with the match results using Vote (individual voting) — OR the winning side collects all ballots and submits them together using VoteMultiple (immediate result) The system verifies the ballots, determines the result by majority vote, and updates each player’s rating Parameters: seasonName: Which season rating system this match belongs to (e.g., “ranked-battle-season-1”) sessionName: A unique identifier for this specific match (shared by all players in the same match) numberOfPlayer: How many players participated in the match (2 to 10) keyId: The encryption key used to sign the ballot (prevents tampering) The returned ballot contains a body (the data) and a signature (proof it hasn’t been tampered with). Both are needed when voting. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot body string Data to be signed signature string Signature Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. vote Submit your ballot to vote on the match result (individual voting) Each player submits their own signed ballot along with the match results (who won and who lost). This is one of two ways to report match results — the simpler approach where each player votes independently. How individual voting works: After the match ends, each player calls CreateVote to get their signed ballot, then calls Vote to submit it The system waits up to 5 minutes from the first vote for all players to vote When all players have voted, or after 5 minutes, the system determines the result by majority vote If votes are tied (e.g., 2 say “Player A won” and 2 say “Player B won”), the result is discarded by default (configurable via script) Rating points are then adjusted for each player based on the determined result This approach is easy to implement but has a delay — results are not reflected until all votes are in or the 5-minute window expires. For immediate results, use VoteMultiple instead, where the winning side collects all ballots and submits them together. Parameters: ballotBody / ballotSignature: The signed ballot obtained from CreateVote gameResults: The match results — a list of participating players with their rank (1st place = winner, 2nd = loser, etc.) keyId: The encryption key used to verify the ballot signature Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ballotBody string  ~ 1024 chars Data for ballot signature targets ballotSignature string  ~ 256 chars Signature gameResults List 0 ~ 10 items Match Results List of user IDs belonging to the player group that participated in the match keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot Implementation Example voteMultiple Collect all ballots and submit match results at once (immediate result) The winning side’s representative player collects the signed ballots from all participants and submits them together with the match results. This approach reflects the result immediately — no waiting for a 5-minute voting window. Why the winning side should collect the ballots: The losing side has an incentive to lie and claim they won, but the winning side has no reason to lie about winning Even if some losing players refuse to hand over their ballots, the result can still be determined as long as a majority of ballots are collected For example, in a 2v2 match, if 3 out of 4 players submit ballots saying “Team A won”, that’s enough for a majority Typical implementation: The match ends and each player calls CreateVote to get their signed ballot Each player sends their ballot (body + signature) to the winning side’s representative player via the game’s communication channel (e.g., real-time server, P2P) The representative player calls VoteMultiple with all collected ballots and the game results The system immediately verifies the ballots, determines the result, and updates all players’ ratings Parameters: signedBallots: List of all collected signed ballots (body + signature pairs from each player) gameResults: The match results — a list of participating players with their rank keyId: The encryption key used to verify the ballot signatures Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). signedBallots List 0 ~ 10 items List of Ballot with signatures gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item EzBallot Ballot Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-SeasonRating SDK for Game Engine\n","title":"GS2-SeasonRating SDK for Game Engine API Reference","url":"/api_reference/season_rating/game_engine/"},{"content":"Models EzSerialKey Serial Code The serial code issued can be used only once. Serial codes are issued in the format “RPCLP-FP7N-NCDMJ-FLVA-IRI4” and the data length cannot be changed. Information on the type of campaign is also included within the serial code. When using the serial code, simply specify the namespace in which the serial code is to be used.  campaignModelName string  ~ 128 chars Campaign name The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the namespace needs to be specified when using the code. 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. code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. status string (enum) enum {   “ACTIVE”,   “USED”,   “INACTIVE” } “ACTIVE” Status The current usage status of this serial code. Transitions from ACTIVE to USED when consumed by a user. The transition is protected by optimistic locking to prevent double-use. INACTIVE codes cannot be used. Definition Description “ACTIVE” Active “USED” Already used “INACTIVE” Disabled (cannot be used) EzCampaignModel Campaign Model A Campaign Model is used to define and manage campaigns, linking them to serial codes.  name string  ~ 128 chars Campaign Model name 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users. Methods getCampaignModel Get the details of a specific serial code campaign Retrieves a single campaign model by name, including its configuration. A campaign model defines a group of serial codes that share the same purpose and settings. For example, you might have separate campaigns for “Launch Bonus Codes”, “Magazine Promotion Codes”, or “Event Giveaway Codes”. The response includes: Campaign name and metadata Whether the campaign is currently active and accepting code redemptions Use this to check campaign details before displaying a code entry screen — for example, to verify the campaign is active before allowing players to enter a serial code. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name Result Type Description item EzCampaignModel Campaign Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. get Look up a serial code’s status Retrieves the details of a specific serial code, including whether it has been used and which campaign it belongs to. Use this to check a code’s status before or after redemption — for example: Showing “This code has already been used” when a player enters a code that was already redeemed Displaying campaign information (what rewards the code gives) before the player confirms redemption Looking up a code for customer support purposes The code should be in the format like “XXXXX-XXXX-XXXXX-XXXX-XXXXX”. The response includes the serial code details and the associated campaign model. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. Result Type Description item EzSerialKey Serial Code campaignModel EzCampaignModel Campaign Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. useSerialCode Redeem a serial code Uses (consumes) a serial code, marking it as redeemed by the current player. Once a code is used, it cannot be used again by anyone. This is the main API for the “Enter Serial Code” feature in your game. The typical flow is: The player opens a “Redeem Code” screen in the game The player types in a serial code (e.g., from a promotional card, email, or website) Your game calls UseSerialCode with the entered code If successful, the code is marked as used — combine this with a reward distribution system to give the player their reward If the code was already used, a “already used” error is returned If the code doesn’t exist, a “code not found” error is returned Common use cases: Promotional codes bundled with merchandise or magazines Gift codes distributed at events or through social media Pre-registration reward codes Partner collaboration codes Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. Result Type Description item EzSerialKey Serial Code campaignModel EzCampaignModel Campaign Model 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 AlreadyUsedException BadRequestException The specified serial code has already been used. CodeNotFoundException NotFoundException The specified serial code does not exist. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-SerialKey SDK for Game Engine\n","title":"GS2-SerialKey SDK for Game Engine API Reference","url":"/api_reference/serial_key/game_engine/"},{"content":"Models EzShowcase Showcase A Showcase can define items for display. Additionally, the sales period for items on Showcase can be set.  name string  ~ 128 chars Showcase name Showcase-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. displayItems List [] 1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Controls the overall sales period of this showcase. When specified, the entire showcase is only available during the associated GS2-Schedule event period. If the event is not active, the showcase returns empty. EzDisplayItem Displayed Item An item displayed on a showcase. Can reference either a single sales item or a sales item group. Each display item can have its own sales period controlled by a GS2-Schedule event, independently of the showcase-level sales period.  displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. type string (enum) enum {   “salesItem”,   “salesItemGroup” }  Type The type of item displayed. A “salesItem” is a single Sales Item with fixed price and rewards. A “salesItemGroup” contains multiple Sales Items evaluated in order, used for step-up pricing or limited purchase discounts. Definition Description “salesItem” Sales Item “salesItemGroup” Sales Item Group salesItem EzSalesItem {type} == “salesItem”  Sales Item * Required if type is “salesItem” salesItemGroup EzSalesItemGroup {type} == “salesItemGroup”  Sales Item Group * Required if type is “salesItemGroup” EzRandomDisplayItem Random Displayed Item on the Random Showcase Represents a Sales Item that has been drawn and displayed on a random showcase for a specific user. Contains the item’s price, rewards, and purchase count tracking for the current rotation period.  name string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. 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. verifyActions List [] 0 ~ 10 items List of Verify Actions consumeActions List [] 0 ~ 10 items List of Consume Actions acquireActions List [] 1 ~ 100 items List of Acquire Actions currentPurchaseCount int  1 ~ 2147483646 Current purchase count The number of times this item has been purchased in the current rotation period. Incremented each time a purchase is made and reset when the rotation period ends. maximumPurchaseCount int  1 ~ 2147483646 Maximum purchase count The maximum number of times this item can be purchased in the current rotation period. Once currentPurchaseCount reaches this value, the item can no longer be purchased until the next rotation. EzSalesItem Sales Item Defines the price required to purchase a Sales Item and the rewards granted upon purchase.  name string  ~ 128 chars Sales Item name Sales Item-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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. EzSalesItemGroup Sales Item Group A Sales Item Group is an entity for display on a Showcase. Multiple Sales Items can belong to a Sales Item Group. Sales Items are evaluated in order, and the first Sales Item determined to be available for purchase is displayed on the Showcase. This can be used for Sales Items that are discounted only for the first purchase, or for systems where the contents change based on the number of purchases, such as a step-up gacha.  name string  ~ 128 chars Sales Item Group name Sales Item Group-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. salesItems List [] 2 ~ 10 items Sales Items included in the Sales Item Group Ordered list of sales items in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name The variable name to be substituted in the transaction template. Corresponds to a placeholder in the transaction action parameters. value string ~ 51200 chars Value The value to substitute for the corresponding variable name in the transaction template. EzConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods buy Buy an item from the showcase Purchases a specific item from a showcase. When the player buys an item, the system automatically handles the entire purchase flow: it checks any requirements (e.g., player level), deducts the cost (e.g., 100 gems), and grants the reward (e.g., a rare sword). This all happens in a single transaction, so the player never loses their payment without receiving the item. Use this when the player taps the “Buy” button on a shop item — for example, purchasing a “Starter Pack” for 500 gems that contains 10 stamina potions and 1 gold chest. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzSalesItem Sales Item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example getShowcase Get a shop Showcase and its items Retrieves a specific Showcase (shop page) and the list of items displayed on it. A Showcase is like a shop screen in your game — for example, a “Gem Shop”, “Daily Deals”, or “Special Offers” page. Each Showcase contains display items, which are the individual products the player can buy. Each product defines what the player pays (cost) and what they receive (reward). Showcases can be linked to schedule events so they only appear during certain periods — for example, a “Holiday Shop” that only shows up during Christmas. Use this to build your shop UI — for example, displaying a list of items with their prices and “Buy” buttons when the player opens the shop screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzShowcase Showcase Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getRandomShowcaseDisplayItem Get a specific item from the random showcase Retrieves the details of a specific item currently displayed on the random showcase. Use this to show the detail view when a player taps on a specific item in the random shop — for example, displaying the item’s full description, price, and a “Buy” button on a detail popup. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. Result Type Description item EzRandomDisplayItem Displayed item Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listRandomShowcaseDisplayItems Get the list of items currently displayed on a random showcase Retrieves the items currently shown on a random showcase for the player. A random showcase is a shop where the displayed items are randomly selected from a pool — like a “Daily Deals” or “Mystery Shop” that shows different items to each player or refreshes periodically. For example, the shop might have a pool of 50 possible items but only display 5 randomly chosen ones at a time, refreshing every day at midnight. The items shown are specific to each player — different players may see different items at the same time. Use this to build the random shop UI — for example, displaying “Today’s Deals” with 5 randomly selected items and a countdown timer until the next refresh. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Displayed Items on Random Showcase Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. randomShowcaseBuy Buy an item from the random showcase Purchases a specific item from the random showcase. Just like buying from a regular showcase, the system automatically handles the entire purchase: checking requirements, deducting the cost, and granting the reward — all in one transaction. Once an item is purchased from the random showcase, it may become unavailable (sold out) depending on the showcase configuration, and the player must wait for the next refresh to see new items. Use this when the player taps “Buy” on an item in the random shop — for example, buying a discounted “Legendary Weapon Box” from the daily deals before it refreshes. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item EzRandomDisplayItem Displayed item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Showcase SDK for Game Engine\n","title":"GS2-Showcase SDK for Game Engine API Reference","url":"/api_reference/showcase/game_engine/"},{"content":"Models EzStatus Status Tracks the skill tree release state for a specific player and property. Maintains a list of released (unlocked) node names. Nodes can be released (added to the list), restrained (removed from the list), or reset (all cleared). Attempting to release an already-released node or restrain a non-released node results in an error. Auto-created when first accessed for a user.  statusId string * ~ 1024 chars Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID releasedNodeNames List [] 0 ~ 1000 items Released Node Names List of node model names that the player has unlocked in this skill tree. Updated by release (add), restrain (remove), and reset (clear all) operations. Maximum 1000 entries. EzNodeModel Node Model Defines a node within the skill tree, including its unlock cost, prerequisites, and refund behavior. Each node can have verify actions (conditions to check before release), consume actions (costs to pay), and prerequisite nodes that must be released first. When a node is restrained (reverted to unreleased), the consumed resources are partially refunded based on the restrain return rate. The return acquire actions are automatically calculated from the consume actions multiplied by the restrain return rate.  name string  ~ 128 chars Node Model name Node 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. releaseVerifyActions List [] 0 ~ 10 items List of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. returnAcquireActions List 0 ~ 10 items Return Acquire Actions List of acquire actions executed when restraining (reverting) this node, representing the resources returned to the player. This field is auto-generated from the release consume actions multiplied by the restrain return rate. For example, if release costs 100 gold and the return rate is 0.8, restraining returns 80 gold. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. EzConfig Configuration Configuration values applied to transaction variables  key string  ~ 64 chars Name value string ~ 51200 chars Value EzAcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods getNodeModel Get the details of a specific skill tree node Retrieves a single node definition by name, including its prerequisites, release cost, and refund settings. Use this to display detailed information when the player taps on a node in the skill tree — for example: “Power Strike” — Requires: Basic Attack (released). Cost: 3 Skill Points. Effect: +50% attack damage. If the node has a restrain return rate of 80%, the player gets back 80% of the cost when reverting this node. The response includes: Prerequisite node names: The list of nodes that must be released first Release consume actions: What the player pays to unlock (e.g., spend 3 skill points) Release verify actions: Conditions checked before allowing release (e.g., player level \u003e= 10) Restrain return rate: The percentage of resources refunded when the node is reverted (0.0 to 1.0) Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). nodeModelName string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzNodeModel Node Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listNodeModels Get a list of all skill tree nodes Retrieves all node definitions in the skill tree. Each node represents a skill, ability, or upgrade that the player can unlock (release) by spending resources. A skill tree is a branching structure where nodes have prerequisites — you must unlock earlier nodes before you can unlock later ones. For example: “Basic Attack” → “Power Strike” → “Critical Slash”, where each node requires the previous one to be released first. Each node definition includes: Prerequisite nodes: Which other nodes must be released before this one can be unlocked Release cost: What resources the player must spend to unlock this node (e.g., skill points, gold, materials) Release conditions: Any additional requirements that must be met (e.g., minimum level) Restrain return rate: What percentage of resources is refunded if the player later reverts (locks) this node Use this to build the skill tree UI — draw all nodes, connect them based on prerequisites, and show which ones are available for release. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Node Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. getStatus Get the player’s skill tree progress Retrieves which nodes the player has released (unlocked) in the skill tree for the specified property ID. The propertyId identifies which skill tree instance to look up. If your game has one skill tree per character, the propertyId could be the character ID. For example, a warrior character and a mage character would each have their own skill tree progress tracked by different propertyIds. Use this to render the skill tree screen — combine with ListNodeModels to get the full tree structure, then overlay the player’s release status to show: Released nodes (unlocked, highlighted) Available nodes (prerequisites met, can be released next) Locked nodes (prerequisites not yet met, greyed out) Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. Result Type Description item EzStatus Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. release Unlock nodes in the skill tree Releases (unlocks) one or more nodes in the skill tree. The player spends the required resources and the nodes become active. This is the “Learn Skill” or “Unlock” button in your skill tree UI. When the player taps a node they want to unlock: The system checks that all prerequisite nodes are already released The system checks release conditions (verify actions) — e.g., minimum player level The system deducts the release cost (consume actions) — e.g., 3 skill points The node is marked as released You can release multiple nodes at once by passing multiple node names. All prerequisites and costs are validated for each node. If any prerequisite is not met, or the player doesn’t have enough resources, the release fails and no resources are consumed. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession nodeModelNames List  1 ~ 1000 items List of Node Model names propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. Result Type Description item EzStatus Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the release process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example reset Reset the entire skill tree (full respec) Reverts ALL released nodes in the skill tree back to unreleased state at once. Resources are refunded based on each node’s restrain return rate. This is the “Reset All Skills” or “Full Respec” button — the player starts their skill tree over from scratch. For example, if a player has released 10 nodes with various costs, all 10 are reverted and the player receives partial refunds for each one based on the configured return rates. Common use cases: A “Respec” feature that lets players rebuild their skill tree with a different strategy Seasonal resets where all players start fresh When game balance changes make the current build suboptimal and you want to let players readjust Unlike Restrain (which selectively reverts specific nodes), Reset affects the entire tree regardless of dependencies. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. Result Type Description item EzStatus Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reset process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example restrain Revert specific nodes back to locked state Reverts (locks) one or more released nodes back to unreleased state. A portion of the resources spent on releasing these nodes is refunded based on each node’s restrain return rate. This is a “partial respec” feature — instead of resetting the entire skill tree, the player can selectively undo specific nodes. For example, if a node cost 100 Gold to release and has a restrain return rate of 0.8 (80%), the player gets back 80 Gold when restraining it. Important rules: You cannot restrain a node if other released nodes depend on it (i.e., nodes that list it as a prerequisite) To restrain a node that is a prerequisite for other released nodes, you must restrain the dependent nodes first This ensures the skill tree always remains in a valid state (no orphaned nodes) Use this for a “remove skill” or “undo” feature in your skill tree UI. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession nodeModelNames List  1 ~ 1000 items List of Node Model names propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. Result Type Description item EzStatus Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the restrain process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool Whether automatic transaction execution is enabled atomicCommit bool Whether to commit the transaction atomically transaction string Issued transaction transactionResult EzTransactionResult Transaction execution result Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-SkillTree SDK for Game Engine\n","title":"GS2-SkillTree SDK for Game Engine API Reference","url":"/api_reference/skill_tree/game_engine/"},{"content":"Models EzStamina Stamina Stamina is a point that is recovered over time in real time. Generally, this stamina is used to limit the number of times a player can play a game per day and to allow the game provider to control the speed of game progression by allowing players to consume stamina to play the game.  staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. value int  0 ~ 2147483646 Stamina Value The current stamina amount for this user, excluding any overflow. This value increases automatically over time based on the recovery interval and recovery value, up to maxValue. It is computed from the elapsed time since lastRecoveredAt using the formula: recoverSteps = elapsedMinutes / recoverIntervalMinutes. overflowValue int  0 ~ 2147483646 Overflow Value The amount of stamina stored in excess of the normal maximum (maxValue). This is only used when the StaminaModel has isOverflow enabled. The total effective stamina is value + overflowValue, capped at maxCapacity. When stamina is consumed, overflow is consumed first before the base value. maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. recoverIntervalMinutes int 1 ~ 2147483646 Stamina Recovery Interval (Minutes) The per-user recovery interval in minutes, resolved from the StaminaModel and optionally overridden by a RecoverIntervalTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverIntervalMinutes. recoverValue int 1 ~ 2147483646 Stamina Recovery Amount The per-user recovery amount per tick, resolved from the StaminaModel and optionally overridden by a RecoverValueTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverValue. nextRecoverAt long Next Recovery Time The Unix timestamp (in milliseconds) when the next stamina recovery tick will occur. Calculated as lastRecoveredAt + recoverIntervalMinutes (in ms). When stamina is already at maxValue, this field may be unset. EzStaminaModel Stamina Model Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience.  name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. For example, if initialCapacity is 100 and maxCapacity is 200, items can boost stamina up to 200 but natural recovery stops at 100. * Required if isOverflow is true maxStaminaTable EzMaxStaminaTable Max Stamina Table Reference to a MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. If not set, all players share the same initialCapacity as their maximum. recoverIntervalTable EzRecoverIntervalTable Recover Interval Table Reference to a RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table using their current rank index, overriding recoverIntervalMinutes. If not set, all players share the same recoverIntervalMinutes. recoverValueTable EzRecoverValueTable Recover Value Table Reference to a RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table using their current rank index, overriding recoverValue. If not set, all players share the same recoverValue. EzMaxStaminaTable Maximum Stamina Table This entity defines the maximum value of stamina for each rank of GS2-Experience.  name string  ~ 128 chars Maximum Stamina Table Name Maximum Stamina Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. EzRecoverIntervalTable Recovery Interval Table This entity defines the stamina recovery interval for each rank of GS2-Experience.  name string  ~ 128 chars Stamina recovery interval table name Stamina recovery interval table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. EzRecoverValueTable Stamina Recovery Amount Table This entity defines the amount of stamina recovery for each rank of GS2-Experience.  name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue. Methods getStaminaModel Get a specific stamina type definition Retrieves the definition for a specific type of stamina. The response includes the recovery interval (how often stamina recovers), recovery amount (how much recovers each time), maximum capacity, and overflow settings. Use this to display the rules for a specific stamina type — for example, showing “Action Stamina: recovers 1 every 5 minutes, max 100” on a stamina detail screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzStaminaModel Stamina Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listStaminaModels Get a list of stamina type definitions Retrieves all stamina model definitions configured in the game. A stamina model defines the rules for a type of stamina — how fast it recovers over time, how much recovers at once, what the maximum capacity is, and whether it can overflow beyond the max. For example, you might have separate stamina models for “Action Stamina” (recovers 1 every 5 minutes, max 100) and “Arena Tickets” (recovers 1 every 2 hours, max 5). Some stamina models can also be linked to player level (via GS2-Experience), so higher-level players automatically get a higher max stamina or faster recovery. Use this to display available stamina types and their rules on a help screen or settings page. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Stamina Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. apply Apply time-based natural recovery to stamina Calculates how much stamina has recovered since the last update based on elapsed time, and applies that recovery to the current value. Stamina recovers automatically over time — for example, if the recovery interval is 5 minutes and recovery amount is 1, the player gains 1 stamina every 5 minutes up to the maximum. Normally, the server calculates recovery automatically when you read the stamina value. Call this explicitly when you need to ensure the latest recovered value is written to the server — for example, before checking if the player has enough stamina for an action that is not managed by GS2 transactions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession Result Type Description item EzStamina Stamina staminaModel EzStaminaModel Stamina Model Implementation Example consume Use (consume) stamina Deducts the specified amount from the player’s current stamina. If the player doesn’t have enough stamina, the request fails with an error — the stamina is never reduced below zero. For example, if a quest costs 20 stamina and the player only has 15, the consumption fails and you can show a “Not enough stamina” message. Note: In most cases, stamina consumption is handled automatically by GS2-Quest or GS2-Showcase when starting a quest or making a purchase. You only need to call this directly if you want to consume stamina outside of those flows — for example, consuming stamina for a custom mini-game or training feature. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession consumeValue int  1 ~ 2147483646 Amount of stamina consumed Result Type Description item EzStamina Stamina staminaModel EzStaminaModel Stamina Model 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 InsufficientException BadRequestException Insufficient remaining stamina. Implementation Example getStamina Get the player’s current stamina for a specific type Retrieves the player’s current stamina value for a specific stamina type, along with its model definition. The response includes the current value, maximum capacity, recovery interval, recovery amount, and overflow amount. Use this to display a specific stamina gauge — for example, showing “Action Stamina: 45/100” with a progress bar and “Full recovery in 4h 35m” on a quest start screen. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession Result Type Description item EzStamina Stamina staminaModel EzStaminaModel Stamina Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listStaminas Get a list of the player’s stamina values Retrieves all of the player’s current stamina values across all stamina types. Each entry shows the current stamina amount, maximum capacity, and recovery status for each stamina type. Use this to display a stamina overview — for example, showing “Action Stamina: 85/100 (full in 1h 15m)” and “Arena Tickets: 3/5 (next in 1h 30m)” on the home screen or status bar. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Staminas nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. setMaxValue Update max stamina based on the player’s level Updates the player’s maximum stamina capacity based on their current level (rank) from GS2-Experience. The stamina model can be configured with a “max stamina table” that maps player levels to max stamina values — for example, level 1 = max 50, level 10 = max 80, level 50 = max 150. When you call this, it reads the player’s current level from the signed GS2-Experience status and looks up the corresponding max stamina from the table. Call this after the player levels up to update their stamina cap — for example, when the player gains a level, call this so their max stamina increases from 80 to 85. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item EzStamina Stamina old EzStamina Stamina staminaModel EzStaminaModel Stamina Model Implementation Example setRecoverInterval Update stamina recovery interval based on the player’s level Updates how frequently the player’s stamina recovers based on their current level (rank) from GS2-Experience. The stamina model can be configured with a “recovery interval table” that maps player levels to recovery intervals (in minutes) — for example, level 1 = recover every 6 minutes, level 20 = every 5 minutes, level 50 = every 3 minutes. Call this after the player levels up so their stamina recovers more frequently — for example, when the player reaches level 20, recovery interval changes from 6 minutes to 5 minutes per stamina point. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item EzStamina Stamina old EzStamina Stamina staminaModel EzStaminaModel Stamina Model Implementation Example setRecoverValue Update stamina recovery amount based on the player’s level Updates how much stamina the player recovers per interval based on their current level (rank) from GS2-Experience. The stamina model can be configured with a “recovery value table” that maps player levels to recovery amounts — for example, level 1 = recover 1 per interval, level 20 = recover 2, level 50 = recover 3. Call this after the player levels up so their stamina recovers faster — for example, when the player reaches level 20, their recovery increases from 1 to 2 per interval, meaning they regain stamina twice as fast. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. gameSession GameSession  GameSession keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item EzStamina Stamina old EzStamina Stamina staminaModel EzStaminaModel Stamina Model Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Stamina SDK for Game Engine\n","title":"GS2-Stamina SDK for Game Engine API Reference","url":"/api_reference/stamina/game_engine/"},{"content":"Models EzStatus State Machine Status Represents a running instance of a state machine for a specific user. Tracks the current execution state including variables, call stack for sub-state machines, transition count, and random number state. The status transitions through Running, Wait, Pass (success), and Error states.  statusId string * ~ 1024 chars Status of State Machine A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Status name Maintains a unique name for each status of state machine. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each status of state machine. enableSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to enable speculative execution When enabled, the state machine definition and random status are included in this Status entity. This allows clients to simulate transitions locally before server confirmation, reducing perceived latency. Definition Description “enable” Enable “disable” Disable stateMachineDefinition string {enableSpeculativeExecution} == “enable” * ~ 16777216 chars State machine definition The GSL definition embedded in this status for speculative execution. Only present when enableSpeculativeExecution is enabled. Filtered out in normal API responses and only included when needed for client-side simulation. * Enabled only if enableSpeculativeExecution is “enable” randomStatus EzRandomStatus {enableSpeculativeExecution} == “enable” * Random status The random number generation state for this execution instance. Used for speculative execution to ensure deterministic random behavior across client and server. Only present when enableSpeculativeExecution is enabled. * Enabled only if enableSpeculativeExecution is “enable” stacks List [] 0 ~ 1024 items Stack The call stack for sub-state machine invocations. When a state machine calls a sub-state machine, an entry is pushed with the caller’s state machine name and return task. When the sub-state machine completes, the entry is popped and execution resumes at the return task. variables List [] 0 ~ 1000 items State variables for each state machine The current variable values for each state machine in the call hierarchy. Each entry holds the state machine name and a JSON-serialized value supporting int, float, string, bool, array, and map types. Variables persist across state transitions within the same execution instance. status string (enum) enum {   “Running”,   “Wait”,   “Pass”,   “Error” } “Running” Status The current execution status of this state machine instance. “Running” means the machine is actively processing transitions. “Wait” means the machine is waiting for an external event (emit). “Pass” means it completed successfully. “Error” means it terminated with an error. Definition Description “Running” Running “Wait” Wait “Pass” Pass “Error” Error lastError string ~ 1024 chars Last error The error message from the most recent failure. Set when the status transitions to “Error”. Contains details about what caused the state machine to terminate abnormally. transitionCount int 0 0 ~ 2147483645 Number of transitions The total number of state transitions performed in this execution instance. Incremented on each transition. If this value exceeds 1000, the state machine is terminated with an error to prevent infinite loops. EzStackEntry Stack Entry Represents a single entry in the sub-state machine call stack. When a state machine invokes a sub-state machine, the caller’s name and the return task are pushed onto the stack. When the sub-state machine completes, execution resumes at the return task of the popped entry.  stateMachineName string  ~ 128 chars Name of the state machine The name of the calling state machine that pushed this stack entry. Used to identify which state machine’s context to restore when returning from a sub-state machine. taskName string  ~ 128 chars Task name The name of the task (state) to return to when the sub-state machine completes. Execution resumes from this task in the calling state machine. EzVariable State variables per state machine Holds the current variable state for a specific state machine within the call hierarchy. The value is a JSON-serialized representation supporting int, float, string, bool, array, and map data types.  stateMachineName string  ~ 128 chars Name of the state machine The name of the state machine that owns these variables. In a nested call hierarchy, each state machine has its own independent variable scope identified by this name. value string  ~ 1048576 chars Value The JSON-serialized variable values for this state machine. Supports int, float, string, bool, array, and map data types. Updated as the state machine processes transitions and actions. EzChangeStateEvent Change state event Records a state transition that occurred within the state machine. Contains the destination task name, a hash for integrity verification, and the timestamp of the transition.  taskName string  ~ 128 chars Task name The name of the destination task (state) that the state machine transitioned to. hash string  ~ 64 chars Hash A hash value for verifying the integrity of the state transition. Used to validate that the transition was performed correctly and the state is consistent. timestamp long  Timestamp EzEmitEvent Send a message event Represents a message emitted by the state machine to trigger external actions. The event name identifies the type of action, and parameters provide the action-specific data.  event string  ~ 128 chars Event name The name identifying the type of emitted event. Used to determine which external action to invoke, such as granting rewards or consuming resources. parameters string  ~ 1024 chars Parameters The parameters passed with the emitted event. Contains action-specific data in a serialized format that is used to configure the external action triggered by this event. timestamp long  Timestamp EzEvent Event Represents an event that occurred during state machine execution. Can be either a state change event (recording a state transition) or an emit event (sending a message to trigger external actions).  eventType string (enum) enum {   “change_state”,   “emit” }  Event type The type of event. “change_state” records a state transition within the state machine. “emit” represents a message sent to trigger external actions such as granting rewards or consuming resources. Definition Description “change_state” Change state “emit” Send a message changeStateEvent EzChangeStateEvent {eventType} == “change_state”  Change state * Required if eventType is “change_state” emitEvent EzEmitEvent {eventType} == “emit”  Send a message * Required if eventType is “emit” EzRandomStatus Random number status Manages the random number generation state for a state machine execution instance. Contains a seed value and per-category usage tracking. Used for speculative execution to ensure deterministic random behavior across client and server.  seed long  0 ~ 4294967294 Random seed The seed value for deterministic random number generation within the state machine execution. used List 0 ~ 1000 items List of used random number Tracks random numbers consumed per category. Each category represents a distinct purpose for random number usage, allowing independent tracking to maintain consistency across speculative re-executions. EzRandomUsed Used random number Tracks the number of random values consumed for a specific category within a state machine execution. Each category allows independent random number tracking for different purposes.  category long  0 ~ 4294967294 Category A numeric identifier for the random number usage category. Each category tracks random consumption independently, allowing the state machine to use separate random sequences for different purposes. used long  0 ~ 4294967294 Used count The number of random values that have been consumed in this category. Incremented each time a random number is drawn from this category’s sequence. EzVerifyActionResult Verify Action execution result  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  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  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  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results Methods emit Send an event to trigger a state transition Sends a named event to the state machine, causing it to move from the current state to the next state based on the defined transition rules. This is the main way the game client drives the state machine forward. For example: Player taps “Accept” on a quest dialog → Emit “accept” event → State changes from “Offered” to “InProgress” Player defeats the boss → Emit “boss_defeated” event → State changes from “BossStage” to “Complete” Player makes a choice in a story → Emit “choose_path_a” event → State branches to the chosen path You can pass additional data as JSON arguments (args). For example, when emitting a “submit_answer” event, you might include {“answer”: “B”} as the args. The state machine will only accept events that are valid for the current state. If the event is not defined for the current state, an error is returned and no transition occurs. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession statusName string  ~ 36 chars Status name eventName string  ~ 36 chars Event name args string “{}” ~ 4096 chars Arguments to be passed to the state machine Result Type Description item EzStatus Status of State Machine Implementation Example exit Clean up a completed state machine Deletes a state machine instance that has finished running. This can only be called when the state machine’s status is “Pass” (completed successfully) or “Error” (failed). After a state machine reaches its terminal state, it remains in the system until you explicitly delete it with Exit. This gives you time to: Show the player the completion result (e.g., “Quest Complete!” screen) Read the final state and variables to determine rewards Handle any error state and decide what to do next Typical flow: State machine reaches terminal state → status becomes “Pass” Game reads the final state and grants rewards to the player Game shows a completion screen Player dismisses the screen → game calls Exit to clean up You cannot call Exit on a Running state machine. If you need to forcefully stop a running state machine, that requires a server-side operation. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession statusName string  ~ 36 chars Status name Result Type Description item EzStatus Exited state machine Implementation Example getStatus Get the current state of a specific state machine instance Retrieves detailed information about a specific state machine instance, including which state it’s currently in and its stored variables. Use this to display the current progress of a workflow to the player — for example: A quest tracker showing “Current step: Defeat 3 monsters (2/3)” A tutorial indicator showing which step the player is on A process status showing whether it’s still running, completed, or encountered an error The response includes: Current state name: Which state the machine is in right now Variables: Data stored in the state machine (e.g., progress counters, choices made) Status: Whether the machine is Running, Pass (completed), or Error Stack trace: The history of state transitions (useful for debugging) Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession statusName string  ~ 36 chars Status name Result Type Description item EzStatus State Machine Status Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listStatuses Get a list of the player’s state machine instances Retrieves all state machine instances belonging to the current player. A state machine is a server-managed workflow that tracks a player’s progress through a series of steps (states). Each step can trigger actions, wait for player input, or branch based on conditions. Common use cases for state machines: Quest progression: “Accept Quest” → “In Progress” → “Boss Battle” → “Complete” → “Claim Reward” Tutorial flows: “Welcome” → “Move Tutorial” → “Battle Tutorial” → “Gacha Tutorial” → “Done” Timed events: Multi-phase event processes with time limits Each state machine instance has one of three statuses: Running: The state machine is active and waiting for the next event Pass: The state machine has completed successfully (reached a terminal state) Error: The state machine encountered an error You can filter by status — for example, to show only active (Running) state machines on the quest screen, or to find completed ones that need cleanup. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession status Status The current execution status of this state machine instance. “Running” means the machine is actively processing transitions. “Wait” means the machine is waiting for an external event (emit). “Pass” means it completed successfully. “Error” means it terminated with an error. Definition Description “Running” Running “Wait” Wait “Pass” Pass “Error” Error pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Status of State Machine nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. report Submit client-side state machine execution results for server validation Sends a batch of events that were processed locally on the game client to the server for validation. This is an optimization feature called “speculative execution” — instead of calling Emit for every single event (which adds network latency each time), the client runs the state machine locally, processes multiple events at once, and then sends all the results to the server in a single call. How speculative execution works: The client has a local copy of the state machine definition When events occur rapidly (e.g., during gameplay), the client processes them locally without waiting for server responses After a batch of events, the client calls Report to send all events to the server The server replays the events and verifies that the final state matches what the client reported If the states match, the server accepts the result. If they don’t match (e.g., client was tampered with), a StateMismatch error is returned This is useful for performance-sensitive scenarios like: Fast-paced gameplay where waiting for server responses would cause lag Offline-capable flows where the player might lose connection temporarily Batch processing of many rapid state transitions Note: Speculative execution must be enabled on the namespace for this API to work. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession statusName string  ~ 36 chars Status name events List 0 ~ 1000 items List of events Result Type Description item EzStatus Status of State Machine 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 StateMismatchException BadRequestException State of the verification result of the report is inconsistent. Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-StateMachine SDK for Game Engine\n","title":"GS2-StateMachine SDK for Game Engine API Reference","url":"/api_reference/state_machine/game_engine/"},{"content":"Models EzAcceptVersion Approved Version Not a version tied to data, such as an app version or asset version. Used for entities that require version control on a per-user basis, such as a version of an agreed upon Terms of Use.  versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. userId string  ~ 128 chars User ID version EzVersion  Version The version number that the user has approved or rejected. When used with “active” scope version models, this version is compared against the model’s current version during version checks. EzVersionModel Version Model You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version.  name string  ~ 128 chars Version Model name Version 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. warningVersion EzVersion {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion EzVersion {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past currentVersion EzVersion {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” EzVersion Version Represents a version number with a three-level hierarchy (major, minor, micro). Version comparison is performed hierarchically: major version is compared first, then minor, then micro. Used to define warning and error thresholds for version checking.  major int  0 ~ 2147483646 Major version The highest priority component in version comparison. A difference in major version takes precedence over minor and micro versions. minor int  0 ~ 2147483646 Minor version The second priority component in version comparison. Compared only when the major versions are equal. micro int  0 ~ 2147483646 Micro version The lowest priority component in version comparison. Compared only when both major and minor versions are equal. EzStatus Version Status Indicates the result of version verification. Contains the version model used for checking and the current version reported by the client or recorded from user approval. Returned as part of version check results to inform the client whether the version is up to date, needs an upgrade warning, or is blocked.  versionModel EzVersionModel  Version Model The version model definition used for this version check. Contains the warning and error version thresholds, scope, and other configuration that determined the check result. currentVersion EzVersion Current Version The version that was evaluated during the version check. For “passive” scope, this is the version declared by the client. For “active” scope, this is the version the user has previously approved. May be absent if no version information is available. EzTargetVersion Version to be verified Represents a version declaration submitted by the client for version checking. In unsigned mode, the version is specified directly. In signed mode, the version is embedded in the body along with a cryptographic signature to prevent tampering.  versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). version EzVersion {signature} == \"\"  Version The version number to be verified. Used when signature verification is not required (no signature provided). When a signature is provided, the version is extracted from the signed body instead. * Required if signature is “\" body string ~ 1048576 chars Body The signed payload containing the version information. Used when signature verification is enabled (needSignature is true). The body contains the version data in a format that can be verified against the signature. signature string ~ 256 chars Signature The cryptographic signature for verifying the body content. When provided, the server validates the signature using the GS2-Key encryption key configured in the version model before accepting the declared version. Methods getVersionModel Get the details of a specific version check definition Retrieves a single version model by name, including its check rules and thresholds. The response includes: Scope: Whether this is a “passive” check (app version — client reports its version) or an “active” check (terms of service — player must explicitly accept) Warning version: The version threshold below which a soft warning is shown (e.g., “A new version is available. Please update.”) Error version: The version threshold below which a hard block is applied (e.g., “You must update to continue playing.”) Current version: The latest version (for active scope, this is what the player needs to accept) Schedule settings: If linked to GS2-Schedule, version thresholds that change over time (e.g., gradually raising the minimum version after a major update) Use this to display version check details or to build custom version check UI logic. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EzVersionModel Version Model Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. listVersionModels Get a list of all version check definitions Retrieves all version models defined in the namespace. Each version model represents a version check rule — for example, “App Version”, “Terms of Service”, or “Asset Version”. GS2-Version supports two types of version checks: App version check (passive scope): The game client reports its own version (e.g., “1.2.3”) and the server checks if it meets the minimum required version. If the client version is below the “warning” threshold → recommend an update (but allow playing) If the client version is below the “error” threshold → force an update (block playing) Terms of service check (active scope): The player must explicitly accept the current version of the terms. If the player hasn’t accepted the latest version → show the terms of service dialog If the player has already accepted → pass the check Use this to find out what version checks are configured, so you can build the appropriate startup flow (version check screen, update prompt, terms dialog, etc.). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Version Models Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. accept Accept a version (agree to terms of service) Records that the player has accepted (agreed to) the specified version. This is the “I Agree” button for terms of service, privacy policy, or similar legal agreements. Typical flow: CheckVersion returns an error for “terms_of_service” because the player hasn’t accepted the latest version Your game shows the terms of service dialog with the full text The player reads and taps “I Agree” Your game calls Accept with the version number that was displayed On the next CheckVersion call, the terms check passes Important: Always pass the version number that was actually shown to the player. If the terms are updated on the server while the player is reading them, passing the old version will cause an error — ensuring the player always agrees to the latest terms. If you don’t specify a version, the latest version is used. However, specifying the version explicitly is recommended to prevent race conditions. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. version EzVersion Approved Version Result Type Description item EzAcceptVersion Approved Version 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 AcceptVersionInvalidException BadRequestException Error as a result of an updated server version during the approval process Implementation Example delete Delete a version acceptance record Removes the player’s acceptance or rejection record for the specified version model. After deletion, the next CheckVersion call will treat the player as if they have never responded to this version check. Use cases: Allow the player to change their mind on optional consents (e.g., withdraw data collection consent) Reset the acceptance state for testing or debugging purposes Force re-acceptance when you want the player to re-read updated terms without changing the version number For active scope checks (terms of service), deleting the acceptance record means the player will be prompted to accept again on their next login or version check. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. Result Type Description item EzAcceptVersion Approved Version deleted Implementation Example list Get a list of versions the player has accepted or rejected Retrieves all version acceptance/rejection records for the current player. Each record shows which version model the player responded to and what version they accepted or rejected. This is mainly used for terms of service and privacy policy management. For example: Show which terms the player has already agreed to and their versions Check if the player needs to re-accept updated terms Display a “Terms and Policies” settings screen where the player can review what they’ve agreed to For app version checks (passive scope), acceptance records are not used — those are checked by comparing the client-reported version directly. This list only contains records for active scope checks (where the player explicitly accepted or rejected). Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession 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 List of Approved Versions nextPageToken string Page token to retrieve the rest of the listing Implementation Example Value change event handling Warning This event is triggered when the value stored in the SDK’s local cache changes. The local cache is updated only when executing the SDK’s API, or by executing stamp sheets via GS2-Distributor with GS2-Gateway notification enabled, or by executing a GS2-JobQueue with GS2-Gateway notification enabled. Therefore, callbacks will not be invoked if the value is changed in any other way. reject Reject a version (decline optional terms) Records that the player has rejected (declined) the specified version. This is the “I Decline” or “No Thanks” button — but only for optional agreements that don’t require acceptance. This can only be used when the version model’s approval requirement is set to “optional”. If approval is required (mandatory), the player must accept — there is no reject option. Use cases for optional terms: Optional data collection consent: “May we collect usage data to improve the game?” → Accept / Decline Optional marketing notifications: “Would you like to receive promotional emails?” → Accept / Decline Optional beta features: “Would you like to try experimental features?” → Accept / Decline Even if the player rejects, the rejection is recorded so you know they’ve seen and responded to the prompt. On the next CheckVersion, the version check passes (since it’s optional), and the game can check the rejection record to adjust behavior accordingly. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. version EzVersion Rejected Version Result Type Description item EzAcceptVersion Rejected Version 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 AcceptVersionInvalidException BadRequestException Error as a result of an updated server version during the approval process Implementation Example checkVersion Run all version checks at once Checks the game client’s versions and the player’s term acceptance status against all version models in the namespace. This is the main API you call at game startup to determine whether the player can proceed or needs to update / accept terms. Typical startup flow: Game launches and calls CheckVersion with the client’s current versions (app version, asset version, etc.) The server checks each version model and returns two lists: warnings: Version checks that passed but the client is below the recommended version (show “Update available” dialog) errors: Version checks that failed — the client is too old or terms haven’t been accepted (block the player) If there are errors, show the appropriate screen: For app version errors → show “Please update from the App Store / Google Play” and redirect For terms of service errors → show the terms dialog and call Accept when the player agrees If there are only warnings (no errors), let the player proceed but optionally show an update recommendation If everything passes with no warnings or errors, the player enters the game normally The targetVersions parameter is where you pass the client’s current version numbers for passive-scope checks (like app version). Active-scope checks (like terms of service) are evaluated automatically based on the player’s acceptance history. Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameSession GameSession  GameSession targetVersions List [] 0 ~ 1000 items List of Versions to be verified Result Type Description projectToken string Signed in to the project token. warnings List Version Verification Results List of Warnings errors List Version Verification Results List of errors Implementation Example","lang":"en","section":"api_reference","summary":"Specifications of models and API references for GS2-Version SDK for Game Engine\n","title":"GS2-Version SDK for Game Engine API Reference","url":"/api_reference/version/game_engine/"},{"content":"The procedure is the same as the general tutorial until the middle of the tutorial. Setup GS2 SDK setup Create credentials (API keys) Prepare resources for login process Initialize client Create environment information First, create a ScriptableObject that defines the environment information. Open the context menu in Project and create Create \u003e Game Server Services \u003e Core \u003e Environment . Create the ScriptableObject you created with create credential (API key) to the ScriptableObject you created. Enter the environment name in the Name field. Create a client holder Next, create a GameObject to hold the GS2 client. Create an appropriate GameObject in the scene. In this case, we have prepared a GameObject named “GS2. Specify the Environment created earlier in Environments and specify the environment name in Active Environment to determine the currently active environment. Although this configuration is made possible to facilitate environment switching, it is recommended that ScriptableObjects such as development environments not be included in the build artifact at the time of product release. OnError can be set to an event handler that is fired if initialization fails. GS2ClientHolder provides a DebugErrorHandler function to dump error messages. In this case, we only need to know that an error has occurred, so we will use this event handler. With this simple setup, the SDK will be initialized on its own when the game starts. Create account and login Create GS2 resource information As you have created the environment, you need to declare the resources available in GS2 as ScriptableObjects. In this case prepare the resources needed for the login process , create the namespace “game-0001” in GS2-Account, and create the namespace “account” in GS2-Key. GS2-Key created a namespace named “account-encryption-key-namespace” and an encryption key named “account-encryption-key”, so we need to reflect those settings. As before, create a ScriptableObject by Create \u003e Game Server Services \u003e Account \u003e Namespace from the Project context menu. Enter the name of the namespace in the ScriptableObject you created. Create a ScriptableObject for GS2-Key in the same way. Implementing the Login Process Although this is called implementation, there is a Prefab that can be placed in the scene to perform the “create account and login” process. With the appropriate GameObject selected in the Hierarchy, open the context menu and select Game Server Services \u003e Core \u003e Action \u003e AutoLogin . A prefab object called Gs2AutoLogin will then be added under the selected node. Specify the ScriptableObject of the GS2-Account namespace in Namespace and the ScriptableObject of the GS2-Key encryption key in Key. OnAutoLoginComplete and OnError are provided as event handlers. OnAutoLoginComplete is called on success, and the process of deactivating its own GameObject is executed. OnError is called on failure, and the GS2ClientHolder’s DebugErrorHandler is called. Visualizing This is where UIKit really comes into its own. Let’s display the login status on the screen. Creating a text node We prepare a hierarchy called View under Canvas and place the text NotLoggedIn / LoggedIn under it. As you can see, the two texts are superimposed in the center of the screen. We will now switch the text to be displayed according to the login status. Show/hide nodes according to login status The UI Kit has a component called “Enabler” that enables or disables a specific node according to its state. Select the View node and add the component. ! You can set display conditions and control targets for the component. When Logged In is unchecked = not logged in, the controlled object will be displayed. Register two components and set which node you want to activate in logged in and un-logged in state respectively. Execution Let’s execute it. You will see the above for a moment, and then it will immediately switch to the following display. In other words, the AutoLogin prefab performs the login process, resulting in the login status changing and the UI display switching on its own. Display your user ID Now let’s use Context, Fetcher and Label. First, we prepare the UI by creating a text node named UserId under LoggedIn. Let’s make this text reflect the user ID of the currently logged in player. Select the LoggedIn node. Add the Gs2AccountOwnAccountContext and Gs2AccountOwnAccountFetcher components. Set the account information you want to display in Gs2AccountOwnAccountContext. Create a ScriptableObject for the Own Account. Own Account is a ScriptableObject for handling account information such as one’s own user ID as context. By specifying this ScriptableObject in the Gs2AccountOwnAccountContext, any Account-related operations under the LoggedIn node using UIKit will be handled as operations on the object specified in the Context. Gs2AccountOwnAccountFetcher is placed next to Gs2AccountOwnAccountContext. This allows Gs2AccountOwnAccountFetcher to retrieve and maintain information about the logged-in user from the server. Next, add a Gs2AccountOwnAccountLabel to the UserId node. Specify the formatting method of the string to be reflected in the text in Format. In this case, we are creating a text that reflects the userId field from the account information obtained by Fetcher. The formatted text is passed to OnUpdate, which reflects it in the text component. Let’s run it again. When the login is complete, the user ID is now displayed in the lower right corner. Did you find the use of the UI Kit strange? Programming in which the code is processed from top to bottom is called Procedural programming . On the other hand, programming like UI Kit is called Declarative Programming . If you find this strange, you have probably been doing mainly Procedural programming . If you are familiar with Procedural programming , you may feel that it is difficult to follow how the side effects of processing occur, and that it is hard to use. On the other hand, the advantage of Declarative programming is that you don’t have to think about side effects, and you can finally define how you want each GameObject to behave, so that the order of processing and who executes it are out of your awareness. Once you understand the difference between Procedural programming and Declarative programming , you will be able to use If you understand the difference between Procedural programming and Declarative programming , you will understand that a description style that declares how you want the UI to behave depending on the state, such as the UI Kit, is a good match for Unity.","lang":"en","section":"get_start","summary":"How to use GS2 UIKit for Unity.\n","title":"GS2 UIKit for Unity Tutorial","url":"/get_start/uikit/"},{"content":"Adding users and credentials (authentication information) can be done from the GS2-Identifier administration screen, but it is easier with GS2-Deploy. GS2-Deploy is a service designed to realize continuous delivery. It allows automatic construction of resources using code written in YAML format. For example, if you create a stack using a template for adding a new user, you can automatically add a new user to GS2-Identifier. About Stacks GS2-Deploy actually operates resources of each service based on a template (which describes how to operate and build resources in GS2). A stack is a collection of resources built using this template. When a template with changed contents is reapplied to the stack, the update process is executed. The system detects differences in changes and automatically creates new resources that need to be created, updates resources that need to be updated, and deletes resources that need to be deleted. This mechanism eliminates the need for the developer to delete resources that are no longer needed, and allows for automatic creation simply by describing the desired resource status in a template. Let’s try to create a stack using a template. The example shows a sample template that creates a user with ApplicationAccess privileges. You can change the user name created for the GS2-Identifier by changing the ApplicationUserName: application part. Download the template Save this template file. Continue by selecting Deploy \u003e Stacks from the side menu of the Management Console. Create a stack by specifying it as template data in Create New Stack. You can check the status of the settings registered in the created stack in the “Execution status” section of the stack. After a few seconds, CREATE_COMPLETE is displayed and the credential setting is complete. After reflection is complete, select the Output tab and you will see the Client ID and Client Secret for the credential. These values will be set in the game app later.","lang":"en","section":"get_start","summary":"Automate setup with GS2-Deploy\n","title":"GS2-Deploy","url":"/get_start/tutorial/setup_credential/deploy/"},{"content":"UI Configuration First, let me show you an overview of the scene. The message list is placed at the top of the screen, and the text input field and send button are placed at the bottom. Context This section describes the placement of Context. A is the room context for GS2-Chat. B is the message list context of GS2-Chat. C is the message context for GS2-Chat. Explanation of implementation Obtaining a message list The room context is set to the information of the room created by GS2-Chat in advance. Two components are attached to the message list context. Gs2ChatMessageListFetcher retrieves a list of messages in a room specified by a room context. Gs2ChatMessageList creates a GameObject based on the data retrieved by the Fetcher. Maximum Items is the maximum number of elements to be created in the list. At startup, Gs2ChatMessageList duplicates and instantiates the GameObject specified as Prefab for the number of Maximum Items. Since it is expensive to re-instantiate the GameObjects as the number of list items increases or decreases, instantiate all GameObjects in advance and hide the ones that are not needed. Example runtime status Mass instantiated Message node. Prefab can be a GameObject with a message context, which will always be set to one of the messages retrieved from the fetcher when displayed. Example runtime status State of the message context assigned to the instantiated Message. Display of Message Three components are attached to the message context. Message is not specified for Gs2ChatMessageContext. This is because it is assumed that the value is set by Gs2ChatMessageList. Gs2ChatMessageFetcher retrieves and stores information about the message specified in Gs2ChatMessageContext. Gs2ChatMessageEnabler is set to activate the Text node once Gs2ChatMessageFetcher has completed retrieving the value. Text is set to Gs2ChatMessageLabel so that the content of the Message’s metadata is reflected in the text. Posting a message To post a message, you need to call GS2-Chat’s Post API. The UI Kit provides a Prefab, Gs2ChatMessagePostAction, for executing Post. This Prefab should be initially disabled because the API will be invoked when it is enabled. Two parameters can be set for the message to be posted. Name Description Category Message Type Metadata Message Body Category can be any number, and can be categorized as “0” is a text message, “1” is a sticker, and so on, and can be used as information to determine how Metadata is read. Metadata is the body of the message. In this sample, only 0 is used for Category, and a raw string is specified for Metadata. OnPostComplete is called on success, disabling its own GameObject and initializing the InputField input to empty. Handling the change of input field value with OnValueChanged in InputField and setting the value to Metadata in Gs2ChatMessagePostAction. Gs2ChatMessagePostAction Prefab is enabled in the OnClick event of the submit button. Confirmation of operation (3 messages exist due to the fact that we checked the operation beforehand) Type ddd and press the submit button. ddd is added to the message list and InputField is initialized. Finally Did you get the fun of Declarative programming of UI Kit? You don’t have to write a process to retrieve the message list after sending a message. You can control the behavior by simply setting up a component to “display the message list” and “reflect the message metadata in the text”.","lang":"en","section":"get_start","summary":"try a more advanced tutorial!","title":"Implementing text chat using UI Kit","url":"/get_start/uikit/chat/"},{"content":"In network feature implementation using GS2, error handling directly impacts game stability and user experience (UX). Here are some practical implementation patterns that go beyond simple exception catching. 1. Error Classification and Handling Policy GS2 exceptions can be broadly classified into three categories based on their nature. Category Applicable Exceptions (Example) Handling Policy Transient Errors InternalServerError , ServiceUnavailable , RequestTimeout Automatic Retry . If it fails after several attempts, display an error dialog. Logic/Configuration Errors BadRequest , NotFound Errors to be resolved during development . After release, collect logs as bugs and display appropriate messages to users. Auth/State Errors Unauthorized , Conflict , QuotaLimitExceeded Special recovery processing required. Perform re-login or data resynchronization (re-acquisition of domain objects). 2. Implementing Retry Strategy (Exponential Backoff) For errors caused by server overload or temporary network instability, “Exponential Backoff,” where retries are spaced out at increasing intervals, is recommended rather than immediate retries. Example in Unity / C# (Automatic Retry) public async Task ExecuteWithAutoRetry (Func \u003e action, int maxRetries = 3) { for (int i = 0; i Determining Manual Retry If RecommendAutoRetry is false and RecommendRetry is true (e.g., ConflictException or QuotaLimitExceededException ), repeating automatically many times may worsen the situation. Therefore, it is common to display a dialog to the user prompting them to retry manually. 3. Automatic Recovery from Authentication Errors ( UnauthorizedException ) When an UnauthorizedException occurs due to an expired access token, ideally, the application should automatically log back in in the background and retry the request rather than prompting the user to return to the title screen. Implementation Image try { await gs2.Inventory.Namespace(\"...\").Me(GameSession).Inventory(\"...\").ModelAsync(); } catch (Gs2.Core.Exception.UnauthorizedException) { // 1. Execute re-login process in the background GameSession = await ReLogin(); // 2. Retry the request using the new GameSession await gs2.Inventory.Namespace(\"...\").Me(GameSession).Inventory(\"...\").ModelAsync(); } 4. Resolving Conflicts ( ConflictException ) A ConflictException may occur if the connection is interrupted during the execution of a stamp sheet. This indicates that “the previous process is not yet complete on the server side, or is duplicated.” Workaround : In many cases, it is resolved by a simple retry. If you are using high-level APIs of the GS2 SDK (Domain objects), there may be an inconsistency between the internal cache and the server state, so it is recommended to re-acquire the Domain object before retrying. 5. User Feedback (UX) Displaying a dialog for every error can be stressful for users. Silent Retry : For transient errors, first retry 1-2 times in the background. During this time, only display a “Communicating…” indicator in the UI. Recoverable Dialog : If the retry still fails, display a message such as “Communication failed. Please try again in a place with good reception” along with [Retry] [Return to Title] buttons. Fatal Error : For maintenance or when a forced app version update is required, display a dedicated dialog that provides no option other than returning to the title screen. Summary Apply Exponential Backoff to retryable errors. Hide authentication errors with Automatic Re-login . Enable Chaos Mode during development to verify that these handlers are working correctly.","lang":"en","section":"articles","summary":"Best practices for practical error handling and retry strategies in game development using GS2.\n","title":"Implementation Patterns for Error Handling","url":"/articles/tech/error/pattern/"},{"content":"This section details the installation process for the SDK for Game Engine, GS2 SDK for Unity or GS2 SDK for Unreal Engine 5. GS2 SDK for Unity Install Instructions GS2 SDK for Unity Installer Version 2024.4.1 Download the installer in UnityPackege format from the link above. Create a new Unity project or prepare an existing Unity project and open it in the Unity Editor. Gs2-unity-installer is available from the menu “Assets \u003e Import Package \u003e Custum Packages…”. Import the gs2-unity-installer_2024.4.1.unitypackage file. Select “Window \u003e Game Server Services \u003e SDK Installer” from the Unity Editor menu. The SDK Installer window will appear. Select ‘Install. When the installation is complete, the SDK is installed in the project’s “Packeges” and can be seen installed in the Package Manager. GS2 SDK for Unity consists of GS2-CSharp-SDK and GS2 SDK for Unity, If it does not work correctly after installation is complete, try restarting the Unity Editor once. GS2 UIKit for Unity installation instructions Select “Window \u003e Game Server Services \u003e UIKit for Unity Installer” from the Unity Editor menu. When the installation is complete, the SDK is installed in the project’s “Packeges” and can be seen installed in the Package Manager. If it does not work properly after installation is complete, try restarting the Unity Editor once. GS2 SDK for Unreal Engine 5 Installation Instructions Install as a project plugin Create a new Unreal project or prepare an existing Unreal project. Clone the source code from the GS2 SDK for Unreal Engine 5 repository on GitHub . Or download it in Zip format and extract it to any folder. Copy the complete source code into your Unreal project. Place it in the following folder in your Unreal project. (Unreal project)/Plugins/Gs2Plugin If the Plugins folder does not exist, create a new one. Create a Gs2Plugin folder in the Plugins folder and copy the complete set of downloaded files into it. Initiate the uproject file in the Unreal Editor. Open the Plugins window and activate the GS2 plugin by checking the box. Restart the Unreal Editor. A dialog box will appear asking if you want to build the GS2 plugin, choose “yes.” Depending on your environment, the build may take a reasonable amount of time. If the plugin builds successfully, the Unreal Editor will launch. The installation is now complete. Installing as an engine plugin You can get the Unreal Engine source code from Github or Perforce and install it as an engine plugin in the environment where you are building the Engine. Clone the source code from GS2 SDK for Unreal Engine 5 repository on GitHub . Or download it in Zip format and extract it to any folder. Create the following folder in the Unreal Engine source code and copy the complete downloaded source code into the folder. (Unreal Engine source code)/Engine/Plugins/Gs2Plugin Run GenerateProjectFiles.bat to update project files. Open the UE5.sln file and build Unreal Engine. Once the build is complete, launch UnrealEditor, enable the GS2 plugin, and restart UnrealEditor. The installation is now complete.","lang":"en","section":"get_start","summary":"Installing GS2-SDK on Unity or Unreal Engine\n","title":"SDK setup","url":"/get_start/tutorial/setup_sdk/"},{"content":"Setup using the management console is attractive because it is easy to perform. However, you must despair when you receive an order to “create another of the same environment”. Game development typically requires multiple server environments: a development environment, a test environment, and a production environment. It is impossible to configure GS2 in each of them by repeating the same operation in the management console without making mistakes. GS2-Deploy GS2 provides GS2-Deploy, a microservice for creating environments. If you are a cloud-savvy engineer, you can understand the role of this microservice simply by saying that it is the GS2 version of Cloud Formation provided by AWS. If you are, you don’t need to read any further; GS2 can orchestrate microservices using Cloud Formation-like functionality. If not, don’t worry. We’ll start explaining GS2-Deploy in detail here. Infrastructure as Code We hope you already understand the folly of using the admin panel to mirror your configuration to GS2. To combat this folly, various improvements have been made in the world of server infrastructure. The result is Infrastructure as Code (IaC). Twenty years ago, infrastructure engineers who needed to spin up a new server would build the environment by typing commands into each server. Install the HTTP server, update the HTTP server configuration file, install the database server, register the schema in the database. This work is fine for one server, but what about setting up 100 servers? It could take a week to set up 100 servers, but some of them would not work because of misconfiguration. In 2006, Amazon launched the Elastic Compute Cloud, the foundation of the modern cloud, and instead of waiting months after placing an order for a server to be delivered, servers were available 5 minutes after the order was placed. This was a game changer in the world of server infrastructure. In the past, we had months of lead time for hardware, so we could fake inefficiency by spending a week setting up the server and fixing any bugs. But then people realized there was something wrong with taking a week to set up a server when you could get one in five minutes. So they became motivated to automate the server setup process and reduce the time spent on setup. The result is IaC, which encodes the server setup process. With IaC, server setup times are fast and accurate. IaC Approaches There are two approaches to IaC. The first is imperative and the second is declarative. The imperative approach is based on the idea of automating the setup process by running a list of commands such as “apt install httpd”. This is a straightforward idea when trying to automate setup procedures that were previously done by humans. The declarative type specifies that “a web server is needed”. At this point, you are not thinking about the steps required to create a web server. So which of these two approaches do you think is better? The best way to judge the superiority of the two approaches is to give a practical example. You are responsible for a service with 100 servers. However, the service has a declining number of users, and you are asked to cut the number of servers in half. You keep 50 servers and shut down the other 50. Six months later, the service is doing well and requires that the 50 servers that were shut down be brought back up to 100 servers. Now, the servers need to be brought up to date after being turned on for the first time in six months, and this is where the difference between imperative and declarative becomes clear. The imperative type does not know how far it has come since the last execution, On the other hand, with a declarative type, if you know the difference between the current state and the newly declared state, you can update the server to fill in the difference. GS2-Deploy implements a declarative type IaC by referring to such past cases. Templates GS2-Deploy declares the state required for each GS2 microservice in a template file, which can be applied to build the environment. Let’s use the template file as it is to create a resource in GS2-Inventory through the Management Console. This completes the template for creating a namespace named test and registering master data. You can build your environment by uploading this file to GS2-Deploy, so you no longer need to be afraid of creating a new environment. Updating GS2-Deploy also behaves wisely in the update process. GS2-Deploy detects differences between the last uploaded template and the newly uploaded template. If find new resource, it creates a new resource. Delete if remove resource. Update if something has changed. This behavior allows a single template file to be edited by many developers without causing problems.","lang":"en","section":"overview","summary":"Create resources in microservices using GS2-Deploy\n","title":"Setup using GS2-Deploy","url":"/overview/workflow/setup_gs2_resources/automation_setup/"},{"content":"First, let’s understand the relationship between an account and a project in GS2. An account and a project have the following data structures. Gs2Account \"1\" *-- \"many\" Gs2Project Gs2Project \"1\" -- \"1\" BillingMethod Gs2Project \"1\" *-- \"many\" GS2Resources","lang":"en","section":"overview","summary":"How to start using GS2\n","title":"Start using GS2","url":"/overview/workflow/setup_gs2/"},{"content":"This section describes transaction processing, which is common to all microservices. Transaction processing policies differ greatly between the for Game Engine and other micro-services. As a general rule, the for Game Engine has more utility classes to make things easier for the developer, and the for Game Engine is different in that it uses utility classes for transaction processing. The difference is that transaction processing is performed using utility classes.","lang":"en","section":"api_reference","summary":"This section describes transaction processing, which is common to all microservices.\nTransaction processing policies differ greatly between the for Game Engine and other micro-services. As a general rule, the for Game Engine has more utility classes to make things easier for the developer, and the for Game Engine is different in that it uses utility classes for transaction processing. The difference is that transaction processing is performed using utility classes.","title":"Transaction processing","url":"/api_reference/transaction/"},{"content":"Game cycle graph TD MainGame[\"Main Game\"] -- Want to get stronger --\u003e Enhance[\"Character Development\"] MainGame[\"Main Game\"] -- I want a character with an advantageous attribute --\u003e Gacha[\"Gacha\"] Gacha -- I want to train the character I got --\u003e Enhance Enhance -- I want to see the results of my character training --\u003e MainGame This is the cycle of the Japanese metagame. As you can see, the starting point for all of this is the gacha. You get a character that has an advantage against the quest’s enemy characteristics through gacha, and then you train that character to achieve a high level of success. The game cycle is to train the obtained characters and clear the high difficulty quests. If you do not intend to make money and just want to maximize player engagement, the source of characters does not have to be gacha. It can be a reward for the main game (e.g., a character joins as the scenario progresses). The following points in this game cycle satisfy players graph TD MainGame[\"Main Game\"] --\u003e Enhance[\"Character Development\"] MainGame[\"Main Game\"] --\u003e Gacha[\"Gacha\"] Gacha -- you got a rare character --\u003e Enhance Enhance -- You completed a quest that you could not clear --\u003e MainGame The essence of this game cycle is not gacha, but a game cycle in which the main game can be played slowly as the character grows over a period of weeks or months. However, it should be understood at the same time that the current position of gacha is an effective position when considering monetization. Character Development Now, let’s delve a little deeper into game design for character development. Even if we simply say “character development,” there are various approaches to realize it. Levels The most obvious growth element is character level. By organizing characters into a party and playing the main game, they gradually gain experience and increase their level. One of the characteristics of games with gacha is that the number of unwanted characters keeps increasing. To solve this problem, it is common to provide a mechanism to gain experience by synthesizing unwanted characters into characters as materials. Players also consider synthesis to be a more reasonable way to gain experience than playing the main game. Level Cap There is a level cap defined for each character. Generally, the lower the character is discharged from the gacha, the higher the level cap is set. However, in some games, low rarity characters have only a low initial level cap and can be raised to the same level as high rarity characters if the level cap is raised. I think this area of design is where the game designers really show their skill. The specific method of raising the level cap is usually achieved by synthesizing the same character or enhancement materials. If we view the former as an economic effort and the latter as a time effort to achieve, it may be easier to formulate a policy on how to reward players. Synthesizing the Same Character In a gacha, you inevitably end up in a situation where you reacquire a character that you have already obtained. The most common use for characters already obtained from a gacha is to be able to raise the character level cap. By synthesizing the same character, the level cap can be raised by 10, which means that the character can become stronger. In many games, there are about five levels of level cap increases available. Synthesizing Enhancement Materials It is also common to be able to raise the level cap by using reinforcement materials that are dropped with a probability of success when conquering quests. Raising the level cap is designed to require materials that only drop in high difficulty quests or have a low drop probability in raising the level cap. Character Characteristics A variety of character characteristics will be provided for characters. One way to play with this is to provide a variety of unique characters and let the player decide which character should be trained now. Elements Attributes such as earth, water, fire, and wind are easy to understand examples. If it is more advantageous to play quests with fire enemies by having water characters in the party, more players will need water characters. Roles The next most obvious role would be the role of attacker, healer, and tank. When organizing a party, it is important to consider not only the attributes but also the roles, as this will add depth to the game. Skills Next, let’s look at skills. There are three types of skills designed for the recovery role. Immediate recovery Gradual recovery Barrier The type of healer that can recover the moment the recovery skill is used will be easy to use. A skill that recovers gradually but the total amount of recovery is more than that of an immediate recovery healer may also raise the game, although the timing of its use may be difficult. Barriers are also interesting. It looks like you can play a technical game where you operate the barrier so that it does not run out so that you do not take damage itself. Elements for training other than characters In addition to characters, it is also common to offer equipment through gacha. Naturally, equipment also has levels and can be developed in the same way as characters. While this is effective from a monetization point of view, too much of it may be too much, and players may not be able to see through it. However, too many of these elements may be overlooked by players. It is also important to strike a balance. Gacha creates a party formation gameplay An interesting side effect of a game cycle in which characters are obtained through gacha is that the players can’t all have the same cards in their hands, so they can’t all have the same cards in their hands. Since everyone will never have the same hand of cards, the question arises as to what is the best party formation for the quest you are about to undertake. The game can be played like a trading card game deck formation. Do I have to pay to enjoy the game? This is a question we often receive from developers who have little experience playing Japanese-style meta-games. Naturally, since you cannot freely organize your party, the range of enjoyment will be less than for players who have paid for the game. However, the game’s management policy addresses this problem by allowing players to play more and more gachas for free. It is also common practice to let players pull 30 free gachas (equivalent to 100 USD) the moment they start the game, and it is also common practice to increase engagement by allowing players to pull one free gacha every day during an event period. It is also common to give away in-game currency needed to draw gachas as you progress in your quest. Generally, if you play every day for a month, even an unpaid player can pull gachas 20 to 30 times in many games. The game that offers the most largesse as far as I know is Granblue Fantasy, but this game regularly holds roulette events where you can randomly draw 10 to 100 free gachas every day. In addition, a few high rarity characters are enough to advance through the game’s main storyline. For dedicated players who want to play the end content with high difficulty level, we can provide a game that can be enjoyed enough even by players without paying. What does it mean to increase the number of players without paying? This may be a question many may ask. A certain percentage of paying players are born from non-paying players. If you do not increase the number of unpaid players, you will not increase the number of paying players. What follows is a shrinking player population. In a long-term game, no matter how much you work to increase engagement, players will leave. Therefore, it makes sense to attract new players, maximize the player population, and increase the number of players who play the end content as much as possible. What are your game sales goals? This depends greatly on the business policy and the economic strength of the region. Generally, in Japan, the game is designed to generate sales of 10 USD per game player per month (ARPU 10 USD). This number includes non-paying players. In other words, players who are spending a lot are paying many times that amount. When designing a game, it is important to keep in mind that there are players who pay as much as 1,000 USD per month. Harakami has sold 5 billion USD in the 27 months since its release. If we consider this as an ARPU of 10 USD, we can take it as an average of 18.5 million people playing the game each month. This is a realistic line since the game has been downloaded more than 110 million times on smartphones alone. (That’s still a tremendous number of players…) 2023-02-11 Kazutomo Niwa","lang":"en","section":"design_knowledge","summary":"What is the Gacha-based meta-game in Japan?","title":"What is Gacha-based meta-game?","url":"/design_knowledge/japanese_metagame/"},{"content":"To call GS2 APIs, you need authentication information (credentials). There are two ways to create credentials. For beginners, we recommend using the Management Console , as the procedure is more intuitive. Create using the Management Console Create using GS2-Deploy","lang":"en","section":"get_start","summary":"Create a credential (API key) to use GS2.","title":"Create credential (API key)","url":"/get_start/tutorial/setup_credential/"},{"content":"First, let’s understand the relationship between projects, regions, and microservices. Projects and microservices have the following data structure. Gs2Project \"1\" *-- \"many\" Region Region \"1\" *-- \"many\" Microservice Microservice \"1\" *-- \"many\" Namespace Namespace \"1\" *-- \"many\" Resource Region A region exists directly under the project. A region represents the region of the data center that GS2 uses to provide microservices. Microservices There are various functions such as property management, matchmaking, in-game stores, etc. These are hosted on a per-region basis, and the microservices database is broken out by region. While real-time communication is appropriate to run on the machine hosted in the region closest to the player, most of the microservices provided by GS2 are mostly functions that do not require as much real-time performance. Therefore, it is possible to deploy only GS2-Realtime in multiple regions, while keeping the other microservices in a single region. Namespace Each microservice can have multiple namespaces. Namespaces are completely separate from each other, but can have multiple spaces. When using GS2-Inventory, you can manage them separately as “namespace to hold consumable items”, “namespace to hold in-game currency”, and “namespace to hold acquired characters”. Resources Each namespace has its own resources. There are two main types of resources. Master data User data Master Data Master Data is an area that holds data predefined by the developer, such as GS2-Inventory, what items exist; GS2-Showcase, what products are sold; GS2-Schedule, what events are scheduled. This is an area that contains data specified by the developer. User Data This is the data that game players individually store. For GS2-Inventory, how many items the player has; for GS2-Quest, which quests the player has already completed. This is data that increases on its own as the game is run. How to Create Resources There are two main ways to create resources: 1. Manual creation from Management Console Log in to the GS2 Management Console from your browser and create resources by entering settings on the UI. This is quick and convenient when you are in the trial-and-error stage or when there are few setting items. 2. Automatic creation using GS2-Deploy (Recommended) Create a template file in YAML format and upload it to GS2-Deploy to automatically create resources. This method is recommended for serious development because of the following benefits: Reproducibility : Resources with the same settings (development environment, production environment, etc.) can be reliably reproduced. Version Control : By managing template files with Git, etc., you can keep a history of setting changes. Batch Management : Resources for multiple services (Inventory, Quest, Account, etc.) can be defined together.","lang":"en","section":"overview","summary":"Create a resource in each GS2 microservice.\n","title":"Create resource in GS2","url":"/overview/workflow/setup_gs2_resources/"},{"content":"","lang":"en","section":"articles","summary":"Miscellaneous development documents\n","title":"Development Documents","url":"/articles/"},{"content":"As a general rule, Game Server Services uses a pay-as-you-go style of pricing. Fee Plans Plan Name Eligibility Price Individual Individuals or corporations with sales of less than 10 million yen in the past 12 months Free Professional Individual plan does not apply to the individual plan Same as usage fee Enterprise Individual plan does not apply to the individual plan ASK Individual Plan Notes The definition of “less than 10 million yen in sales over the past 12 months” includes sales from other businesses, not sales from games using GS2. If the average number of requests per month exceeds 10 requests per second, or 100 requests per second continuously for a period of time, you will not be eligible for the individual plan. If you are ineligible, we will consider the time it will take to modify your application, but please act quickly. If you are launching a game under the Individual Plan, you must include the GS2 logo in the “Launch Sequence” or “Title Screen”. You will receive the logo data and guidelines for display via chat when you are ready to release your game. Free Slots You can continue to use the Professional/Enterprise plan free of charge until you exceed the 100USD monthly limit. Once you exceed 100USD, you will be charged for the entire usage amount, not just the excess. Usage Fees General Fees API request or List API request: When retrieving 30 or more records, in batches of 30 Tier Prices - 100,000,000 0.0001 USD 100,000,001 - 500,000,000 0.00008 USD 500,000,001 - 2,500,000,000 0.00006 USD 2,500,000,001 - 7,500,000,000 0.00004 USD 7,500,000,001 - 0.00003 USD Annual Lump-Sum Payment 36,000 USD/year per 100,000,000 requests/month usage commitment No refunds will be issued even if monthly usage falls below the commitment. Usage fees exceeding the commitment will be calculated based on the monthly commitment tier. Pricing Example Assumption: Committing to 1,000,000,000 requests/month Upfront payment: 360,000 USD Example 1: 500,000,000 requests/month (below commitment) Monthly payment: 0 USD/month Total: 360,000 USD + 0 USD/year (0 USD * 12 months) = 360,000 USD Under standard pricing, this would be 42,000 USD/month = 504,000 USD/year. Therefore, even if actual usage falls below the commitment, you save 144,000 USD/year. Example 2: 3,000,000,000 requests/month (2,000,000,000 requests over) Monthly payment: 1,500,000,000 requests * 0.00006 USD + 500,000,000 requests * 0.00004 USD = 110,000 USD Total: 360,000 USD + 1,320,000 USD (110,000 USD * 12 months) = 1,680,000 USD Standard usage fee would be 194,000 USD/month = 2,328,000 USD/year, resulting in a savings of 64,800 USD/year Additional fees per service GS2-Datastore Action Unit Price Data storage bytes 1GB 0.1 USD Data download bytes 1GB 0.3 USD GS2-Freeze Action Unit Price Basic materials Stage/mo 3,000 USD Stages using versions older than 1 month(Additional) Stage/mo 30,000 USD When using GS2-Freeze, please devote maximum resources to keeping up with the latest version. Fixing the GS2 code base with GS2-Freeze may improve stability, but may slow down the speed at which vulnerabilities are addressed. GS2-Guard Action Unit Price Basic materials Namespace/mo 200 USD API Requests Tier Price - 10,000,000 0.00005 USD 10,000,001 - 50,000,000 0.00004 USD 50,000,001 - 250,000,000 0.00003 USD 250,000,001 - 750,000,000 0.00002 USD 750,000,001 - 0.00001 USD GS2-Log action unit price On-Demand GS2-Insight Usage 1 minute 0.01 USD Log entries per item Tier Price - 10,000,000 0.00005 USD 10,000,001 - 50,000,000 0.00004 USD 50,000,001 - 250,000,000 0.00003 USD 250,000,001 - 750,000,000 0.00002 USD 750,000,001 - 0.00001 USD Additional charge when GS2 is specified as the log storage location Action Unit Price Log bytes 1GB 0.05 USD Log reference Scanning bytes 1GB 0.02 USD GS2-Money In addition to the normal API usage fee, a revenue share of the amount in monthly circulation will be applied. Monthly circulation amount range Revenue 0 USD 〜 9,999 USD 10% 10,000 USD 〜 99,999 USD 5% 100,000 USD 〜 999,999 USD 3% 1,000,000 USD 〜 9,999,999 USD 1% 10,000,000 USD 〜 1,000,000,000 USD 0% The usual free allowance does not apply to revenue sharing, but if the monthly circulation amount is less than 100 USD, no fee will be charged as an exception. GS2-Money2 If the overall GS2 fee is less than the revenue share shown below, the revenue share for the monthly distribution amount will be applied. Consumption content Monthly circulation amount range Revenue 0 USD 〜 9,999 USD 10% 10,000 USD 〜 99,999 USD 5% 100,000 USD 〜 999,999 USD 3% 1,000,000 USD 〜 9,999,999 USD 1% 10,000,000 USD 〜 1,000,000,000 USD 0% Subscription Content 1% of subscription amount Special Notes The usual free allowance does not apply to revenue sharing, but if the monthly circulation amount is less than 100 USD, no fee will be charged as an exception. GS2-News Actions Units Prices Site build 1 pattern 0.01 USD Site data download bytes 1GB 0.03 USD GS2-Ranking Global Ranking Action Unit Price Aggregate Processing 10,000 scores for ranking 0.02 USD Scope Ranking Action Unit Price score registration 10 score subscriptions 0.0001 USD GS2-Realtime specs units price realtime1.nano 1 minute 0.0004 USD realtime1.micro 1 minute 0.0006 USD realtime1.small 1min 0.0012 USD realtime1.medium 1min 0.0024 USD realtime1.large 1 minute 0.005 USD action unit price Data transfer bytes (outbound) 1GB 0.15 USD Hot Standby Action Unit Price realtime1.nano 1 unit (from 5 units)/month 15 USD realtime1.micro 1 unit (from 5 units)/month 22.5 USD realtime1.small 1 unit (from 5 units)/month 55 USD realtime1.medium 1 unit (from 5 units)/month 110 USD realtime1.large 1 unit (from 5 units)/month 230 USD GS2-Script action unit price Script execution time 1 second 0.00005 USD GS2-SerialKey action unit price Serial Code Issuance 1 code 0.00005 USD Special Operations in All Microservices actions units prices Exporting user data 1 item 0.00001 USD Complete deletion of user data 1 item 0.00002 USD Import of user data 1 item 0.00002 USD One item refers to one piece of user data managed internally by GS2. The operation shown here is executed by specifying a user ID, and processing for multiple items will occur depending on the number of items of data stored at the time of this execution.","lang":"en","section":"pricing","summary":"About Game Server Services Fees.\n","title":"GS2 usage fees","url":"/pricing/"},{"content":"The procedure is the same as in the general tutorial up to the halfway point. GS2 setup SDK setup Create credentials (API keys) Prepare resources for login process Initialize client Create a GS2::Core::Action::Initialize node and set clientId / clientSecret / region to connect to. Set clientId / clientSecret to the values you created in Create Credential (API Key) . OnSuccess is called if initialization succeeds, and OnError is called if it fails. On success, a GS2 client object is returned in Client, and on failure, an error object with the reason for the failure is returned in Error. Create GS2-Account client Create a GS2::Account::Service node with the Client object obtained during initialization. A service client for GS2-Account functionality is returned in Service. Generate Namespace object Create a GS2::Account::Namespace node specifying the GS2-Account service client. For Namespace Name, specify the namespace name created in Prepare resources required for login process . A GS2-Account Namespace object is returned in Namespace. Create a new anonymous account Create a GS2::Account::Action::Create node with the Namespace object of GS2-Account. OnSuccess is called if the account is successfully created, and OnError is called if it fails. In case of success, the created account object is returned in Account, and in case of failure, an error object with the reason for the failure is returned in Error. Retrieving values from an account object Create a GS2::Account::Fetch::GetValueOfAccount node with an account object. OnSuccess is called if the account value is successfully retrieved, and OnError is called if it fails. On success, the value of the account object is returned in Value, and on failure, an error object with the reason for the failure is returned in Error. By expanding the structure, the issued user ID and password can be retrieved. Login Create a GS2::Core::Action::Login node to perform the login process. The GS2::Core::Action::Login node requires the specification of Client and Authenticator. For Client, specify the Client created by the GS2::Core::Action::Initialize node. For Authenticator, specify the Authenticator created by the GS2::Core::CreateGs2Authenticator node. UserId / Password specifies the UserId and Password created earlier. OnSuccess is called if the login succeeds, and OnError is called if it fails. On success, an AccessToken object is returned in AccessToken, and on failure, an Error object is returned in Error, indicating the reason for the failure. The access token is a parameter required for API calls that require login. API calls that can be invoked after login As an example of API calls that can be invoked after login, let’s try to get a list of transfer information. Create your own account object in GS2::Account::Me using the access token object. Then create a GS2::Account::Fetch::ListOfTakeOver node using your account object to get a list of takeover information. OnSuccess is called if the list of takeover information is successfully retrieved, and OnError is called if not. In case of success, an array of transfer information is returned in Values, and in case of failure, an error object with the reason of failure is returned in Error. Values is looped through in the For Each Loop node and the values are retrieved.","lang":"en","section":"get_start","summary":"implement GS2-SDK for UE5 Blueprint to create an account and login","title":"GS2-SDK for UE5 Blueprint Tutorial","url":"/get_start/blueprint/"},{"content":"UI Configuration First, let me show you the scene as a whole. The upper part of the screen shows the inventory capacity usage, the list of possessed items is in the center, and the buttons to obtain items are at the bottom. Context This section describes the placement of Context. A is the inventory context for GS2-Inventory. B is the item list context for GS2-Inventory. C is the item context in GS2-Inventory. D is the exchange rate context for obtaining a Potion for free on GS2-Exchange. E is the exchange rate context for obtaining Ether for free on a GS2-Exchange. Implementation Description Display inventory consumption capacity The InventoryWindow node has a context specifying the GS2-Inventory inventory and a Fetcher that retrieves the inventory information. Text is set to Gs2InventoryInventoryLabel, which reflects the string Current Consumed Capacity / Maximum Capacity in the value of the text component. Get a list of items Gs2InventoryOwnItemSetFetcher to get a list of items in the inventory. Gs2InventoryOwnItemSetList duplicates the 100 Item nodes, and then The context information of the items in the Gs2InventoryOwnItemSetContext of each Item node is set as the context information. Displaying Items The Item node has a Gs2InventoryOwnItemSetContext, but no ScriptableObject is set here, because the value is set by the Gs2InventoryItemSetList. Fetcher retrieves the item model and possession information, respectively. In Name, Gs2InventoryItemModelLabel is used to reflect the retrieved item name in the text component. Count uses Gs2InventoryOwnItemSetLabel to reflect the quantity of the acquired item in the text component. The Gs2InventoryItemSetConsumeAction prefab is placed under the Use node, with a consumption quantity of 1. The type of item to be consumed is determined by the context, and the item specified in the Item node that exists in the parent hierarchy is consumed. It is then set to deactivate itself if the consumption process is successful. A button is placed in the Use node, which is set to activate the Gs2InventoryItemSetConsumeAction prefab when clicked. This causes the behavior to consume one item when the button is clicked. Obtaining items Since the API for obtaining items cannot be called from within the game, this time GS2-Exchange is set up to provide an exchange rate for obtaining each item for free, and the item can be obtained by executing the exchange. Under the Acquire Potion node, a Gs2ExchangeExchangeAction prefab is placed, with the exchange quantity specified as 1. It is then configured to deactivate itself if the exchange process is successful. The Acquire Potion node has an exchange rate context set, which specifies the rate at which the exchange will be performed. A button component is also in place, and clicking the button activates the Gs2ExchangeExchangeAction prefab. The Acquire Ether node is similarly configured, with the exchange rate set to the exchange rate at which Ether is obtained instead of Potion. Confirmation of operation Upon activation, you will initially see an empty list as you do not have any items and an inventory consumption of 0/10. Click on Acquire Potion. ![img_26.png] Since the exchange rate is to obtain 10 potions in one exchange, 10 Potion are now displayed in the list of items. Next, let’s click Acquire Ether. A second line has been added and the Ether has increased. Let’s try exchanging Potion 10 more times. Since Potion is configured to have 99 stacks, it is now divided into 99 stacks and 11 stacks. Let’s try consuming the Potion by clicking the Use button on the stack of 99. The number of Potion is now 98. Next, let’s try consuming Potion by clicking the Use button on a stack of 11. The number of Potion is now 10. Finally It must have been a bit of a surprise to see how far we could go with no code at all, wasn’t it? We will continue to explain more about the UI Kit. Please check out the rest of the article.","lang":"en","section":"get_start","summary":"try a more advanced tutorial!","title":"Implement item inventory using UI Kit","url":"/get_start/uikit/inventory/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting changePasswordIfTakeOver bool false Whether to change the password when taking over the account Specifies whether to change the password when taking over the account. This setting allows you to restrict logins from the device used before the takeover after the takeover is completed. differentUserIdForLoginAndDataRetention bool false Whether to use different user IDs for login and data retention Specifies whether to use different user IDs for login and data retention. This setting may help comply with privacy requirements defined by the platform provider with less implementation effort. *This parameter can only be set when creating a namespace. createAccountScript ScriptSetting Script to run when creating an account Used to implement custom logic for creating an account. Script Trigger Reference - createAccount authenticationScript ScriptSetting Script to run when authenticated Used to implement custom logic for authentication. Script Trigger Reference - authentication createTakeOverScript ScriptSetting Script to run when creating a takeover If you want to give a reward when you register TakeOver Information for the first time, you can use this to add custom logic to increase the GS2-Mission counter. Script Trigger Reference - createTakeOver doTakeOverScript ScriptSetting Script to run when taking over Used to implement custom logic for taking over. Script Trigger Reference - doTakeOver banScript ScriptSetting Script to run when adding Account Ban Status Script Trigger Reference - ban unBanScript ScriptSetting Script to run when removing Account Ban Status Script Trigger Reference - unBan logSetting LogSetting Log Output Setting Manages Log Output Setting. This type holds the GS2-Log namespace information used to output log data. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Account Game Player Account An entity of identity information that identifies a game player. Game player accounts are anonymous accounts and consist of a user ID (UUID) and password (a random 32-character string), so game players do not need to enter their email address or other information. The issued Game Player Account is stored in the device’s local storage and is used for future logins. Details  accountId string * ~ 1024 chars Game Player Account A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  UUID ~ 128 chars User ID password string  ~ 128 chars Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account. timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. banStatuses List [] 0 ~ 10 items List of Account Ban Statuses Stores detailed information about the BAN (access restriction) status associated with the account. Each entry contains the reason for the BAN, the period, and other related information. banned bool false Whether the Account is currently banned Indicates Whether the Account is currently banned. If true, the Account is in an access-restricted state, and if false, it is accessible. lastAuthenticatedAt long Last authenticated time The last time the Account was authenticated. This value is updated each time the Account is authenticated. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TakeOver TakeOver Information TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately. Details  takeOverId string * ~ 1024 chars TakeOver Information A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision PlatformId Platform ID Holds IDs for various platforms such as X, Instagram, and Facebook. Other players can search for players using various platform IDs. When importing Instagram followers or Facebook friends as in-game friends, it is used to identify the GS2-Account account. Details  platformId string * ~ 1024 chars Platform Id A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision DataOwner Data Owner A Data Owner is used when “Whether to use different user IDs for login and data retention” is specified in the namespace settings. The user ID that can be obtained when a Data Owner ID that is different from the user ID is issued and an access token is received through the GS2-Account authentication process is the Data Owner ID. Details  dataOwnerId string * ~ 1024 chars Data Owner setting A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID name string  UUID ~ 36 chars Data Owner ID Serves as a unique identifier for the data owner. The data owner ID represents the actual owner of the data and may be different from the user ID. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TakeOverTypeModel TakeOver Type Model This model defines TakeOver Information. TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately. Details  takeOverTypeModelId string * ~ 1024 chars Takeover Type Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. OpenIdConnectSetting OpenID Connect Configuration By registering the settings of an OpenID Connect-compliant IdP, IdP integration can be configured and used as TakeOver Information. Details  configurationPath string  ~ 1024 chars OpenID Connect Configuration URL The discovery endpoint URL of the OpenID Connect provider. Must follow the well-known format (e.g., https://example.com/.well-known/openid-configuration). clientId string  ~ 1024 chars Client ID The client ID of the application registered with the IdP. clientSecret string {configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Client Secret * clientSecret is required when the configurationPath is not “https://appleid.apple.com/.well-known/openid-configuration”, i.e., for other IdP integrations. appleTeamId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Team ID of Apple Developer The team ID from the Apple Developer account. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” appleKeyId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Key ID registered with Apple The key ID registered in the Apple Developer account for Sign in with Apple. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” applePrivateKeyPem string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 10240 chars Private Key received from Apple The private key in PEM format downloaded from the Apple Developer portal. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” doneEndpointUrl string ~ 1024 chars Redirect URL after authentication is completed If not specified, it will transition to /authorization/done. id_token is attached to the Query String. additionalScopeValues List [] 0 ~ 10 items Additional scopes obtained with OpenID Connect Additional OAuth scopes to request from the IdP beyond the default OpenID Connect scopes. Allows retrieving extra user information during authentication. additionalReturnValues List [] 0 ~ 10 items Additional values returned from OpenID Connect Additional claim names from the ID token or UserInfo response to include in the return values. Specified claims are extracted and returned alongside the standard authentication result. ScopeValue Scope Value A key-value pair representing an additional OAuth scope value obtained during OpenID Connect authentication. Used to store extra data retrieved from the IdP beyond the standard OpenID Connect claims. Details  key string  ~ 64 chars Name The scope name that was requested from the IdP during authentication. value string ~ 51200 chars Value The value returned by the IdP for the corresponding scope. PlatformUser Various platform user information Holds user information from external platforms. Contains the mapping between a platform-specific user identifier and the corresponding GS2-Account user ID, used for searching players by their platform identity. Details  type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform user is linked to. Used to map between external platform identities and GS2 anonymous accounts. BanStatus Account Ban Status Represents information about the BAN (access restriction) status applied to a Game Player Account. This type includes detailed information such as the reason for the BAN, the name of the BAN, and the scheduled date and time for the BAN to be lifted. Ban status can be applied to an account for various reasons, such as cheating or violation of the terms of service, and this type helps to manage that status. The system uses this information to control the account’s access permissions and to restrict or release access as necessary. Details  name string  UUID ~ 36 chars Ban status name Maintains a unique name for each Ban status. The name can be set to any value. If omitted, it is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Ban status. This ID allows for easy tracking of multiple Ban statuses. reason string  ~ 256 chars Reason for BAN Explains the specific reason for the BAN. It can be up to 256 characters long and helps to clarify the cause of the BAN. This information is not only referenced by the account administrator and the operations team, but also included in the response value to the game client. releaseTimestamp long  Date and time when the BAN will be released Indicates the date and time when the Account Ban will be released. Once this date and time has passed, the account will be automatically released from the BAN and normal access will be possible. CurrentModelMaster Master data of the currently active TakeOver Type Model This master data defines the TakeOver Type Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Account Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data TakeOverTypeModelMaster TakeOver Type Model Master TakeOver Type Model Master is data used to edit and manage TakeOver Type Models within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as TakeOver Type Model actually referenced by the game. TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately. Details  takeOverTypeModelId string * ~ 1024 chars Takeover Type Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. description string ~ 1024 chars Description 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting changePasswordIfTakeOver bool false Whether to change the password when taking over the account Specifies whether to change the password when taking over the account. This setting allows you to restrict logins from the device used before the takeover after the takeover is completed. differentUserIdForLoginAndDataRetention bool false Whether to use different user IDs for login and data retention Specifies whether to use different user IDs for login and data retention. This setting may help comply with privacy requirements defined by the platform provider with less implementation effort. *This parameter can only be set when creating a namespace. createAccountScript ScriptSetting Script to run when creating an account Used to implement custom logic for creating an account. Script Trigger Reference - createAccount authenticationScript ScriptSetting Script to run when authenticated Used to implement custom logic for authentication. Script Trigger Reference - authentication createTakeOverScript ScriptSetting Script to run when creating a takeover If you want to give a reward when you register TakeOver Information for the first time, you can use this to add custom logic to increase the GS2-Mission counter. Script Trigger Reference - createTakeOver doTakeOverScript ScriptSetting Script to run when taking over Used to implement custom logic for taking over. Script Trigger Reference - doTakeOver banScript ScriptSetting Script to run when adding Account Ban Status Script Trigger Reference - ban unBanScript ScriptSetting Script to run when removing Account Ban Status Script Trigger Reference - unBan logSetting LogSetting Log Output Setting Manages Log Output Setting. This type holds the GS2-Log namespace information used to output log data. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting changePasswordIfTakeOver bool false Whether to change the password when taking over the account Specifies whether to change the password when taking over the account. This setting allows you to restrict logins from the device used before the takeover after the takeover is completed. createAccountScript ScriptSetting Script to run when creating an account Used to implement custom logic for creating an account. Script Trigger Reference - createAccount authenticationScript ScriptSetting Script to run when authenticated Used to implement custom logic for authentication. Script Trigger Reference - authentication createTakeOverScript ScriptSetting Script to run when creating a takeover If you want to give a reward when you register TakeOver Information for the first time, you can use this to add custom logic to increase the GS2-Mission counter. Script Trigger Reference - createTakeOver doTakeOverScript ScriptSetting Script to run when taking over Used to implement custom logic for taking over. Script Trigger Reference - doTakeOver banScript ScriptSetting Script to run when adding Account Ban Status Script Trigger Reference - ban unBanScript ScriptSetting Script to run when removing Account Ban Status Script Trigger Reference - unBan logSetting LogSetting Log Output Setting Manages Log Output Setting. This type holds the GS2-Log namespace information used to output log data. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeAccounts Get a list of Game Player Accounts Get a list of all Game Player Accounts in the specified namespace. The information for the Accounts retrieved includes the Account ID, status, and creation date. Supports pagination, limits the number of Accounts that can be retrieved at one time, and provides a token for the next page. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Game Player Accounts nextPageToken string Page token to retrieve the rest of the listing Implementation Example createAccount Create a new Game Player Account This method creates a new Game Player Account. No user ID or password is required to create an Account. The user ID and password are automatically generated. When the creation is successful, the details of the newly created Account are returned as a response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Account Game player Account created Implementation Example updateTimeOffset Update the correction value for the current time of the game player’s Account Update the correction value for the current time of the specified game player’s Account. This time correction can be used to test future event schedules in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account updated Implementation Example updateBanned Update on Account Ban Status of Game Player Account This is used to update the BAN (access restriction) status of a specific Game Player Account. The Ban status of an Account can be enabled or disabled, which restricts the Account’s use in the game. Specify the Account ID and the new Ban status to update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID banned bool false Whether the Account is currently banned Indicates Whether the Account is currently banned. If true, the Account is in an access-restricted state, and if false, it is accessible. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account updated Implementation Example addBan Add the Account Ban Status for a Game Player Account Used to add a new Account Ban Status to a Game Player Account. You can set temporary or permanent access restrictions for a specific Account. To add a BAN, you must specify the Account ID and the Ban status (including reason and duration). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID banStatus BanStatus  Ban status timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account updated Implementation Example removeBan Delete the Account Ban Status for a Game Player Account This is used to delete the Ban status applied to a specific Game Player Account. To delete, specify the User ID and the name of the Ban status to be deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID banStatusName string  ~ 36 chars Ban status name timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account updated Implementation Example getAccount Get a Game Player Account Get detailed information about a specific Game Player Account with the specified ID. The information retrieved includes the Account name, status, and creation date. This method is used to display detailed information about an Account. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  UUID ~ 128 chars User ID includeLastAuthenticatedAt bool false Include last authenticated at timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account Implementation Example deleteAccount Delete Game Player Account This is used to delete a specific Game Player Account. When an Account is deleted, it can no longer be logged in with that Account, but any user data that is not managed by GS2-Account will remain in GS2. If you need to delete all user data as well, please use the user data complete deletion function accessible from the management console. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  UUID ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account deleted Implementation Example authentication Authenticate Game Player Account Used to authenticate a Game Player Account. When a user logs in to an Account, the username and password are checked. If the correct authentication information is provided, the Account information and its signature are issued. By passing this information to GS2-Auth, you can obtain an access token and access GS2’s various microservices as a user who has logged in. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN password string  ~ 128 chars Password Stores the password for securing the account. Passwords can be up to 128 characters long and play an important role in protecting your account. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Account Game Player Account banStatuses List Ban status list body string Account information for signing subject signature string signature Implementation Example describeTakeOvers Get a list of TakeOver Information Retrieves a list of TakeOver Information registered for the currently logged-in Game Player Account. TakeOver Information is used to transfer account data when changing devices or reinstalling the game. Supports pagination, allowing you to retrieve a limited number of records at a time and use a token to fetch the next page. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of TakeOver Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeTakeOversByUserId Get a list of TakeOver Information by specifying a user ID Retrieves a list of TakeOver Information registered for the specified Game Player Account. TakeOver Information is used to transfer account data when changing devices or reinstalling the game. Supports pagination, allowing you to retrieve a limited number of records at a time and use a token to fetch the next page. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of TakeOver Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example createTakeOver Create a new TakeOver Information Registers new TakeOver Information for the currently logged-in Game Player Account. The caller must specify a type slot (numeric), a user identifier (e.g., email address), and a password. The registered information can later be used to recover the account on a different device by providing the same user identifier and password. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item TakeOver TakeOver Information created Implementation Example createTakeOverByUserId Create a new TakeOver Information by specifying a user ID Registers new TakeOver Information for the specified Game Player Account. The caller must specify a type slot (numeric), a user identifier (e.g., email address), and a password. The registered information can later be used to recover the account on a different device by providing the same user identifier and password. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TakeOver TakeOver Information created Implementation Example createTakeOverOpenIdConnect Create a new TakeOver Information using OpenID Connect Registers new TakeOver Information for the currently logged-in Game Player Account using an OpenID Connect ID Token. Instead of a password, the caller provides an ID Token obtained from an identity provider (e.g., Google, Apple). The subject (user identifier) is automatically extracted from the ID Token and associated with the account. The corresponding Takeover Type Model must have an OpenID Connect setting configured in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. idToken string  ~ 10240 chars OpenID Connect ID Token Result Type Description item TakeOver TakeOver Information created Implementation Example createTakeOverOpenIdConnectAndByUserId Create a new TakeOver Information using OpenID Connect by specifying a user ID Registers new TakeOver Information for the specified Game Player Account using an OpenID Connect ID Token. Instead of a password, the caller provides an ID Token obtained from an identity provider (e.g., Google, Apple). The subject (user identifier) is automatically extracted from the ID Token and associated with the account. The corresponding Takeover Type Model must have an OpenID Connect setting configured in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. idToken string  ~ 10240 chars OpenID Connect ID Token timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TakeOver TakeOver Information created Implementation Example getTakeOver Get TakeOver Information Retrieves the TakeOver Information of the specified type registered for the currently logged-in Game Player Account. The retrieved information includes the type slot, user identifier, and creation date. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description item TakeOver TakeOver Information Implementation Example getTakeOverByUserId Get TakeOver Information by specifying a user ID Retrieves the TakeOver Information of the specified type registered for the specified Game Player Account. The retrieved information includes the type slot, user identifier, and creation date. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TakeOver TakeOver Information Implementation Example updateTakeOver Update TakeOver Information Updates the password of the TakeOver Information of the specified type for the currently logged-in Game Player Account. The old password must be provided for verification before the new password can be set. If the old password does not match, a PasswordIncorrect error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. oldPassword string  ~ 128 chars Old Password password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item TakeOver TakeOver Information updated Implementation Example updateTakeOverByUserId Update TakeOver Information by specifying a user ID Updates the password of the TakeOver Information of the specified type for the specified Game Player Account. The old password must be provided for verification before the new password can be set. If the old password does not match, a PasswordIncorrect error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. oldPassword string  ~ 128 chars Old Password password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TakeOver TakeOver Information updated Implementation Example deleteTakeOver Delete TakeOver Information Deletes the TakeOver Information of the specified type from the currently logged-in Game Player Account. Once deleted, the account can no longer be recovered using the user identifier and password of the deleted TakeOver Information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description item TakeOver TakeOver Information deleted Implementation Example deleteTakeOverByUserIdentifier Delete TakeOver Information by specifying user Identifier Deletes the TakeOver Information by looking it up using the platform-side user identifier instead of the GS2 user ID. This is useful when you know the external user identifier (e.g., email address) but not the internal GS2 user ID. Once deleted, the account can no longer be recovered using the user identifier and password of the deleted TakeOver Information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string ~ 1024 chars User ID for takeover Result Type Description item TakeOver TakeOver Information deleted Implementation Example deleteTakeOverByUserId Delete TakeOver Information by specifying a user ID Deletes the TakeOver Information of the specified type from the specified Game Player Account using the GS2 user ID. Once deleted, the account can no longer be recovered using the user identifier and password of the deleted TakeOver Information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TakeOver TakeOver Information deleted Implementation Example doTakeOver Execute Account Takeover Executes the account takeover (recovery) process using a user identifier and password. This is used when a user wants to recover their account on a new device or after reinstalling the game. If the user identifier and password match a registered TakeOver Information, the associated Game Player Account is returned. If the password does not match, a PasswordIncorrect error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. userIdentifier string  ~ 1024 chars User ID for takeover A unique key used to identify an individual when taking over an account. If the same userIdentifier is specified for different accounts, the value set later will take precedence. password string  ~ 128 chars Password For security reasons, this password is treated as confidential information and only the hash value is stored. Result Type Description item Account Game Player Account Implementation Example doTakeOverOpenIdConnect Execute Account Takeover using OpenID Connect Executes the account takeover (recovery) process using an OpenID Connect ID Token. This is the OIDC variant of the takeover execution, where the caller provides an ID Token from an identity provider (e.g., Google, Apple) instead of a password. The ID Token is validated and the subject is used to look up the associated Game Player Account. The corresponding Takeover Type Model must have an OpenID Connect setting configured in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. idToken string  ~ 10240 chars OpenID Connect ID Token Result Type Description item Account Game Player Account Implementation Example getAuthorizationUrl Get authorization URL Returns the authorization URL for the OpenID Connect flow of the specified takeover type. The client can use this URL to redirect the user to the identity provider’s authorization page. This is the entry point for initiating the OAuth/OIDC authorization flow for account takeover. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different TakeOver Information. Result Type Description authorizationUrl string Authorization URL Implementation Example describePlatformIds Get a list of Platform IDs The Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Platform IDs nextPageToken string Page token to retrieve the rest of the listing Implementation Example describePlatformIdsByUserId Get a list of Platform IDs by specifying GS2-Account user ID Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Platform IDs nextPageToken string Page token to retrieve the rest of the listing Implementation Example createPlatformId Create a new Platform ID Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. Result Type Description item PlatformId Platform ID created Implementation Example createPlatformIdByUserId Create a new Platform ID by specifying GS2-Account user ID Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PlatformId Platform ID created Implementation Example getPlatformId Get Platform ID The Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. Result Type Description item PlatformId Platform ID Implementation Example getPlatformIdByUserId Get Platform ID by specifying a user ID The Platform ID is information used to hold IDs for various platforms such as X, Instagram, and Facebook. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PlatformId Platform ID Implementation Example findPlatformId Find GS2-Account user ID by specifying Platform ID If “Whether to use different user IDs for login and data retention” is enabled in the namespace settings, you can get the data owner ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. Result Type Description item PlatformUser Various platform user information Implementation Example findPlatformIdByUserId Get Platform ID by specifying GS2-Account user ID If “Whether to use different user IDs for login and data retention” is enabled in the Namespace settings, you can get the data owner ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string  ~ 1024 chars User ID on various platforms The user’s unique identifier on the external platform (e.g., social media user ID or email address). Used together with the slot number (type) to identify a specific platform account. dontResolveDataOwner bool? false Disable Data Owner ID resolution when different User IDs are used for login and data retention Set true to not resolve data owner ID even if ‘Whether to use different user IDs for login and data retention’ is enabled in the namespace settings. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PlatformUser Various platform user information Implementation Example deletePlatformId Delete Platform ID Deletes the Platform ID of the specified type from the currently logged-in Game Player Account. Once deleted, the association between the GS2 account and the platform identity is removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string ~ 1024 chars User ID for platform id Result Type Description item PlatformId Platform ID deleted Implementation Example deletePlatformIdByUserIdentifier Delete Platform ID by specifying a user ID on various platforms Deletes the Platform ID by looking it up using the platform-side user identifier instead of the GS2 user ID. This is useful when you know the external user identifier on the platform but not the internal GS2 user ID. Once deleted, the association between the GS2 account and the platform identity is removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. userIdentifier string ~ 1024 chars User ID for platform id Result Type Description item PlatformId Platform ID deleted Implementation Example deletePlatformIdByUserId Delete Platform ID by specifying GS2-Account user ID Deletes the Platform ID of the specified type from the specified Game Player Account using the GS2 user ID. Once deleted, the association between the GS2 account and the platform identity is removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars GS2-Account User ID The GS2-Account user ID that this platform ID is linked to. Used to map between external platform identities and GS2 anonymous accounts. type int  0 ~ 1024 Slot Number Specified within the range from 0 to 1024, it is used to identify the type of platform. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PlatformId Platform ID deleted Implementation Example getDataOwnerByUserId Get Data Owner This action is used to get information about a data owner associated with a specified user ID. This action returns detailed information about a data owner associated with a specific account in the specified namespace. Data owner information includes data owner ID, associated user ID, and other related information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  UUID ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataOwner DataOwner Implementation Example updateDataOwnerByUserId Update Data Owner Updates the data owner name associated with the specified user ID. The data owner is used to manage the mapping between the user ID used for login and the user ID used for data retention when “Whether to use different user IDs for login and data retention” is enabled in the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  UUID ~ 128 chars User ID dataOwnerName string  UUID ~ 36 chars Data Owner ID Serves as a unique identifier for the data owner. The data owner ID represents the actual owner of the data and may be different from the user ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataOwner DataOwner Implementation Example deleteDataOwnerByUserId Delete Data Owner This action is used to delete information about a data owner associated with a specified user ID. This action completely deletes the data owner associated with the specified account in the specified namespace from the system. The relationship between the user ID and the data owner ID is lost, and it is unknown whose data it is unless the user ID is included in the user data managed by GS2. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  UUID ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataOwner The deleted Data Owner Implementation Example describeTakeOverTypeModels Get a list of TakeOver Type Models Retrieves all currently active TakeOver Type Models in the specified namespace. TakeOver Type Models define the types of account takeover methods available, such as email/password-based or OpenID Connect-based takeover. Each type model includes settings such as the OpenID Connect configuration for the identity provider. Unlike the master variant, this returns only the activated (published) models without pagination. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of TakeOver Type Models Implementation Example getTakeOverTypeModel Get TakeOver Type Model Retrieves the currently active TakeOver Type Model of the specified type in the specified namespace. The type model includes the OpenID Connect configuration and other settings for the identity provider associated with this takeover type. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. Result Type Description item TakeOverTypeModel TakeOver Type Model Implementation Example exportMaster Export TakeOver Type Model Master in a master data format that can be activated Exports the current TakeOver Type Model Master data in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster TakeOver Type Model master data that can be activated Implementation Example getCurrentModelMaster Get master data of the currently active TakeOver Type Model Retrieves the master data of the TakeOver Type Models that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Master data of the currently active TakeOver Type Model Implementation Example preUpdateCurrentModelMaster Update master data of the currently active TakeOver Type Model (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster in preUpload mode, passing the token used for the upload, to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentModelMaster Update master data of the currently active TakeOver Type Model Updates and activates (publishes) the master data of the TakeOver Type Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentModelMaster Updated master data of the currently active TakeOver Type Model Implementation Example updateCurrentModelMasterFromGitHub Update master data of the currently active TakeOver Type Model from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentModelMaster Updated master data of the currently active TakeOver Type Model Implementation Example describeTakeOverTypeModelMasters Get a list of TakeOver Type Model Masters Retrieves a paginated list of TakeOver Type Model Masters in the specified namespace. TakeOver Type Model Masters are the editable versions of TakeOver Type Models that define the types of account takeover methods available. Changes to master data do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of TakeOver Type Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createTakeOverTypeModelMaster Create a new TakeOver Type Model Master Creates a new TakeOver Type Model Master that defines a type of account takeover method. You can configure the type slot (numeric), description, metadata, and OpenID Connect settings for the identity provider. The OpenID Connect settings include the client ID, client secret, issuer, and other OIDC configuration required for identity provider integration. Changes do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. description string ~ 1024 chars Description 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. Result Type Description item TakeOverTypeModelMaster TakeOver Type Model Master created Implementation Example getTakeOverTypeModelMaster Get TakeOver Type Model Master Retrieves a specific TakeOver Type Model Master by type in the specified namespace. The retrieved information includes the type slot, description, metadata, and OpenID Connect settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. Result Type Description item TakeOverTypeModelMaster TakeOver Type Model Master Implementation Example updateTakeOverTypeModelMaster Update TakeOver Type Model Master Updates the specified TakeOver Type Model Master. You can change the description, metadata, and OpenID Connect settings for the identity provider. Changes do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. description string ~ 1024 chars Description 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. Result Type Description item TakeOverTypeModelMaster TakeOver Type Model Master updated Implementation Example deleteTakeOverTypeModelMaster Delete Takeover Type Model Master Deletes the specified Takeover Type Model Master from the specified namespace. Once deleted, this takeover type will no longer be available after the next master data activation. This operation only affects the master data; the currently active model remains unchanged until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. Result Type Description item TakeOverTypeModelMaster TakeOver Type Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Account SDK for various programming languages\n","title":"GS2-Account SDK API Reference","url":"/api_reference/account/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when ad viewing rewards are granted, including auto-run, atomic commit, and asynchronous processing options. admob AdMob AdMob settings Manages settings and parameters related to ads. unityAd UnityAd Unity Ads settings Manages settings and parameters related to ads. appLovinMaxes List 0 ~ 10 items AppLovin MAX settings Manages settings and parameters related to ads. acquirePointScript ScriptSetting Script setting to be executed when points are acquired Script Trigger Reference - acquirePoint consumePointScript ScriptSetting Script setting to be executed when points are consumed Script Trigger Reference - consumePoint changePointNotification NotificationSetting  Push notification when point changes This is a push notification setting when the point changes. This setting holds the information necessary to notify the game client when the point changes. If you do not make this setting, the points you earn will not be reflected in the game immediately. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log namespace information used to output log data. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Point Ad Viewing Points Records the total number of points earned by the player by viewing ads. Each time a player views an ad, they earn points, which can be used to exchange rewards or purchase in-game benefits. Details  pointId string * ~ 1024 chars Point A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID point long 0 0 ~ 9223372036854775805 Number of points held Indicates the number of points held by the user. This value increases as the user views ads and decreases as they exchange rewards and benefits. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision AdMob AdMob settings Stores a list of allowed ad unit IDs and uses it to verify AdMob’s viewing completion Webhook. Details  allowAdUnitIds List  1 ~ 10 items List of allowed ad unit IDs Used to verify the ad unit ID included in the ad viewing completion callback from AdMob. The ad unit IDs included in this list are used to verify that the ad viewing was completed properly in the application or game. By checking whether the ad unit ID included in the notification of ad viewing completion sent from the AdMob platform is in this list, you can accept only legitimate ad viewing events and prevent invalid requests and spam. UnityAd Unity Ads settings Used to store the Unity Ads-related cryptographic keys used by the application or game. The cryptographic keys are issued by Unity Ads and are used to verify the completion of ad viewing. Details  keys List 0 ~ 10 items List of cryptographic keys Stores a list of cryptographic keys issued by Unity Ads. These keys are used to communicate with the Unity Ads ad platform and to verify ad events. Encryption keys can be obtained from the Unity Dashboard. Each key in the list is required to verify the completion of ad viewing. AppLovinMax AppLovin MAX settings Stores an allowed ad unit ID and uses it to verify the AppLovin MAX viewing completion Webhook. Details  allowAdUnitId string  ~ 16 chars Allowed Ad Unit ID Used to verify the ad_unit_id included in the AppLovin MAX ad viewing completion callback. The ad viewing event is accepted only when the ad_unit_id in the callback matches the configured ad unit ID. This prevents unauthorized callbacks, invalid requests, and fraudulent reward claims from unregistered ad units. eventKey string  ~ 128 chars AppLovin Event Key Used to verify that the completion callback from AppLovin MAX is accessed from the appropriate source. Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when ad viewing rewards are granted, including auto-run, atomic commit, and asynchronous processing options. admob AdMob AdMob settings Manages settings and parameters related to ads. unityAd UnityAd Unity Ads settings Manages settings and parameters related to ads. appLovinMaxes List 0 ~ 10 items AppLovin MAX settings Manages settings and parameters related to ads. acquirePointScript ScriptSetting Script setting to be executed when points are acquired Script Trigger Reference - acquirePoint consumePointScript ScriptSetting Script setting to be executed when points are consumed Script Trigger Reference - consumePoint changePointNotification NotificationSetting  Push notification when point changes This is a push notification setting when the point changes. This setting holds the information necessary to notify the game client when the point changes. If you do not make this setting, the points you earn will not be reflected in the game immediately. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log namespace information used to output log data. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when ad viewing rewards are granted, including auto-run, atomic commit, and asynchronous processing options. admob AdMob AdMob settings Manages settings and parameters related to ads. unityAd UnityAd Unity Ads settings Manages settings and parameters related to ads. appLovinMaxes List 0 ~ 10 items AppLovin MAX settings Manages settings and parameters related to ads. acquirePointScript ScriptSetting Script setting to be executed when points are acquired Script Trigger Reference - acquirePoint consumePointScript ScriptSetting Script setting to be executed when points are consumed Script Trigger Reference - consumePoint changePointNotification NotificationSetting  Push notification when point changes This is a push notification setting when the point changes. This setting holds the information necessary to notify the game client when the point changes. If you do not make this setting, the points you earn will not be reflected in the game immediately. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log namespace information used to output log data. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example getPoint Get current Point status Returns the point information associated with the currently logged-in user. If the user has no existing point record, a new record is automatically created with 0 points and returned. This allows you to check how many points the user currently holds from ad viewing rewards. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Point Ad Viewing Points Implementation Example getPointByUserId Get Point status by specifying a user ID Returns the point information associated with the specified user ID. If the user has no existing point record, a new record is automatically created with 0 points and returned. This allows you to check how many points the user currently holds from ad viewing rewards. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Point Ad Viewing Points Implementation Example acquirePointByUserId Acquire Points by specifying a user ID Adds a specified number of points to the specified user ID and returns the updated point information. If the user has no existing point record, a new record is automatically created before adding points. If a GS2-Script is configured in the namespace’s acquire script settings, the script is executed before the point addition, allowing custom validation or modification of the acquire amount. After the point addition, a change notification is sent if configured in the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID point long  1 ~ 9223372036854775805 Acquire Points timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Point Point Implementation Example consumePoint Consume Points Subtracts a specified number of points from the currently logged-in user and returns the updated point information. An error is returned if the user does not have enough points to cover the requested consumption amount. If a GS2-Script is configured in the namespace’s consume script settings, the script is executed before the point deduction, allowing custom validation or modification of the consume amount. After the point deduction, a change notification is sent if configured in the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token point long  1 ~ 9223372036854775805 Consume Points Result Type Description item Point Point Implementation Example consumePointByUserId Consume Points by specifying a user ID Subtracts a specified number of points from the specified user ID and returns the updated point information. An error is returned if the user does not have enough points to cover the requested consumption amount. If a GS2-Script is configured in the namespace’s consume script settings, the script is executed before the point deduction, allowing custom validation or modification of the consume amount. After the point deduction, a change notification is sent if configured in the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID point long  1 ~ 9223372036854775805 Consume Points timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Point Point Implementation Example deletePointByUserId Delete Points by specifying a user ID Deletes the point record for the specified user ID, resetting the user’s points to their initial state (0 points). This operation is irreversible; however, subsequent Get or Acquire operations will automatically create a new point record with 0 points. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Point Point Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-AdReward SDK for various programming languages\n","title":"GS2-AdReward SDK API Reference","url":"/api_reference/ad_reward/sdk/"},{"content":"Models AccessToken Access token A model that manages access tokens issued after user authentication. Access tokens are used to identify a session while a user is logged in to the service. Tokens have an expiration time, and when they expire, re-authentication is required. Details  token string  ~ 1024 chars Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. userId string  ~ 128 chars User ID federationFromUserId string ~ 128 chars Federation original user ID The user ID of the original user who initiated the ID federation. When a user acts on behalf of another user through ID federation, this field stores the initiating user’s ID. expire long The absolute time 1 hour after the current time Expiration time A timestamp indicating the expiration time of the token. When this date is reached, the token becomes invalid. Unix time, milliseconds timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. Methods login Log in to GS2 by specifying a user ID Logs into GS2 with the specified user ID and obtains an access token. This API is intended to be called from a trusted game server. It is inappropriate to call it from the client, as there is no validation process for the user ID value. You can optionally specify a time offset (in seconds) to pseudo-advance the current time for the logged-in user, which is useful for testing future event schedules. The returned access token has an expiration time, after which it becomes invalid. Details Request  userId string  ~ 128 chars User ID timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description token string Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. 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 Implementation Example loginBySignature Log in to GS2 with account authentication information Log in to GS2 by verifying signed account authentication information and obtain an access token. By performing signature verification of the signed authentication payload, this API is safe to call from clients. The body and signature are typically obtained from the GS2-Account Authentication API, and the key ID specifies the GS2-Key encryption key used for signature verification. The returned access token has an expiration time, after which it becomes invalid. Details Request  keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN body string  ~ 524288 chars Signed authentication payload signature string  ~ 1024 chars Signature Result Type Description token string Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. 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 Implementation Example federation Federation of user IDs Obtains an access token that allows you to act as another user based on the specified original user ID. This is useful for scenarios such as guild-to-member operations, where a guild master needs to perform actions on behalf of another user. When issuing a transaction using this access token, #{userId} in the transaction action is replaced with the federated user ID, and #{originalUserId} is replaced with the original user ID. By specifying a policy document, you can set stricter constraints on the permissions that the credentials have as a federated user when calling the API. The returned access token has an expiration time, after which it becomes invalid. Details Request  originalUserId string  ~ 128 chars Federation original user ID userId string  ~ 128 chars Federated user ID policyDocument string ~ 524288 chars Policy document timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description token string Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. 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 Implementation Example issueTimeOffsetTokenByUserId Issue a time offset token usable with the specified user ID Time offset token can be used to pseudo-advance the time for API processing by specifying the user ID in APIs that do not require an access token. If you want to use a time offset with an API that uses an access token, you can specify the time offset when issuing the access token to execute the equivalent processing without specifying the token for each request. The time offset token has its own expiration period, which is different from that of a regular access token. This is primarily used for testing purposes, such as verifying the behavior of scheduled events or time-limited content in advance. Details Request  userId string  ~ 128 chars User ID timeOffset int 0 0 ~ 315360000 Time offset from the current time (number of seconds relative to the current time) The time offset represents the difference from the current server time in seconds. This value is used when in-game events or features need to operate according to a specific time. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description token string Access token A token used to authenticate access. This token is automatically generated by the system and identifies the user’s session. 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 Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Auth SDK for various programming languages\n","title":"GS2-Auth SDK API Reference","url":"/api_reference/auth/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration that controls how distributed transactions based on buff application results are executed, including options such as AutoRun, AtomicCommit, and asynchronous processing. applyBuffScript ScriptSetting Script setting to be executed when applying buffs Script Trigger Reference - apply logSetting LogSetting Log Output Setting Configuration for outputting log data of buff operations to GS2-Log. Specifies the GS2-Log namespace where API request and response logs are collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” BuffTargetModel Buff Target Model Defines the target GS2 resource model and field for buff application. Specifies which model’s field value should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply. Details  targetModelName string (enum) enum { }  Model type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric field on the target model whose value will be modified by the buff. For example, a field representing experience points, attack power, or other numerical attributes. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Adjustment rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the field value after rate calculations. BuffEntryModel Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period. Details  buffEntryModelId string * ~ 1024 chars Buff Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Buff Entry Model name Buff Entry 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Add to adjustment rate “mul” Multiply the adjustment rate by the specified value “value_add” Directly add values (only numerical values for models or actions) targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active. BuffTargetAction Buff Target Action Defines the target GS2 action and parameter for buff application. Specifies which action’s parameter should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply. Details  targetActionName string (enum) enum { \"Gs2Experience:AddExperienceByUserId\" , \"Gs2Experience:SubExperience\" , \"Gs2Experience:SubExperienceByUserId\" , \"Gs2Inventory:AcquireItemSetByUserId\" , \"Gs2Inventory:ConsumeItemSet\" , \"Gs2Inventory:ConsumeItemSetByUserId\" , \"Gs2Inventory:AcquireSimpleItemsByUserId\" , \"Gs2Inventory:ConsumeSimpleItems\" , \"Gs2Inventory:ConsumeSimpleItemsByUserId\" , \"Gs2Inventory:AcquireBigItemByUserId\" , \"Gs2Inventory:ConsumeBigItem\" , \"Gs2Inventory:ConsumeBigItemByUserId\" , \"Gs2Limit:CountUp\" , \"Gs2Limit:CountUpByUserId\" , \"Gs2Money:DepositByUserId\" , \"Gs2Money:Withdraw\" , \"Gs2Money:WithdrawByUserId\" , \"Gs2Money2:DepositByUserId\" , \"Gs2Money2:Withdraw\" , \"Gs2Money2:WithdrawByUserId\" , \"Gs2Stamina:ConsumeStamina\" , \"Gs2Stamina:ConsumeStaminaByUserId\" , \"Gs2Stamina:RecoverStaminaByUserId\" , }  Action type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric parameter on the target action whose value will be modified by the buff. For example, a parameter representing acquire count, consume amount, or reward quantity. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the parameter value after rate calculations. BuffTargetGrn GRN pattern that identifies the resources used as conditions for applying buffs Specifies a GRN template with placeholders to identify which resource instance the buff should be applied to. The model name identifies the GS2 service model, and the GRN pattern contains context variables (e.g., region, ownerId, namespaceName) that are resolved at runtime to match the target resource. Details  targetModelName string  ~ 64 chars Buff application condition model name The name of the GS2 service model used to resolve the condition GRN. This identifies which service’s resource model the GRN pattern refers to. targetGrn string  ~ 1024 chars Buff application condition GRN A GRN template with context placeholders (e.g., {region}, {ownerId}) that is resolved at runtime to identify the specific resource instance targeted by the buff. OverrideBuffRate Buff application rate override model Allows overriding the rate value of a specific BuffEntryModel at the time of buff application. By specifying the buff entry name and a custom rate, the default rate defined in the BuffEntryModel can be replaced with a different value for a particular request. Details  name string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rate float  0 ~ 100 Rate The override rate value to use instead of the default rate defined in the BuffEntryModel. CurrentBuffMaster Master data of the currently active Buff Entry Models Master data that defines the Buff Entry Models currently active in the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Buff Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data BuffEntryModelMaster Buff Entry Model Master Buff Entry Model Master is data used to edit and manage Buff Entry Models within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Buff Entry Model actually referenced by the game. The amount of buff is managed by the BuffEntryModel, and multiple BuffEntryModels can be associated with a specific target entry. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period. Details  buffEntryModelId string * ~ 1024 chars Buff Entry Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Rate Add “mul” Mul “value_add” Value Add targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a List of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration that controls how distributed transactions based on buff application results are executed, including options such as AutoRun, AtomicCommit, and asynchronous processing. applyBuffScript ScriptSetting Script setting to be executed when applying buffs Script Trigger Reference - apply logSetting LogSetting Log Output Setting Configuration for outputting log data of buff operations to GS2-Log. Specifies the GS2-Log namespace where API request and response logs are collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration that controls how distributed transactions based on buff application results are executed, including options such as AutoRun, AtomicCommit, and asynchronous processing. applyBuffScript ScriptSetting Script setting to be executed when applying buffs Script Trigger Reference - apply logSetting LogSetting Log Output Setting Configuration for outputting log data of buff operations to GS2-Log. Specifies the GS2-Log namespace where API request and response logs are collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example applyBuff Apply buff Evaluates all Buff Entry Models in the specified namespace and applies the applicable buffs to the currently logged-in user. Buffs are evaluated according to their priority (smaller values are evaluated first), and support three application methods: Rate Add (adds to the adjustment rate), Mul (multiplies the adjustment rate), and Value Add (directly adds to values). If a Buff Entry Model is associated with a GS2-Schedule event, it is only applied during the event period. Returns the list of applied buffs and an updated context stack that records the buff application state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of applied buffs newContextStack string Context stack after applying buff Implementation Example applyBuffByUserId Apply buff by specifying a user ID Evaluates all Buff Entry Models in the specified namespace and applies the applicable buffs to the specified user. Buffs are evaluated according to their priority (smaller values are evaluated first), and support three application methods: Rate Add (adds to the adjustment rate), Mul (multiplies the adjustment rate), and Value Add (directly adds to values). If a Buff Entry Model is associated with a GS2-Schedule event, it is only applied during the event period. Returns the list of applied buffs and an updated context stack that records the buff application state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of applied buffs newContextStack string Context stack after applying buff Implementation Example describeBuffEntryModels Get a list of Buff Entry Models Retrieves all currently active Buff Entry Models in the specified namespace. Buff Entry Models define the buff effects that can be applied to game data, including the application method (Rate Add, Mul, Value Add), target (model or action), and priority. Unlike the master variant, this returns only the activated (published) models without pagination. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Buff Entry Models Implementation Example getBuffEntryModel Get Buff Entry Model Retrieves the currently active Buff Entry Model with the specified name in the specified namespace. The retrieved information includes the application method (Rate Add, Mul, Value Add), target type (model or action), target details, priority, and the associated GS2-Schedule event if configured. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). buffEntryName string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BuffEntryModel Buff Entry Model Implementation Example exportMaster Export Buff Entry Model Master in a master data format that can be activated Exports the current Buff Entry Model Master data in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentBuffMaster Buff Entry Model master data that can be activated Implementation Example getCurrentBuffMaster Get master data of the currently active Buff Entry Models Retrieves the master data of the Buff Entry Models that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentBuffMaster Master data of the currently active Buff Entry Models Implementation Example preUpdateCurrentBuffMaster Update master data of the currently active Buff Entry Models (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentBuffMaster Update master data of the currently active Buff Entry Models Updates and activates (publishes) the master data of the Buff Entry Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentBuffMaster Updated master data of the currently active Buff Entry Models Implementation Example updateCurrentBuffMasterFromGitHub Update master data of the currently active Buff Entry Models from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentBuffMaster Updated master data of the currently active Buff Entry Models Implementation Example describeBuffEntryModelMasters Get a list of Buff Entry Model Masters Retrieves a paginated list of Buff Entry Model Masters in the specified namespace. Buff Entry Model Masters are the editable versions of Buff Entry Models that define the buff effects applicable to game data. Changes to master data do not take effect until the master data is activated (published) via the Current Buff Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by buff entry model name prefix 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 List of Buff Entry Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createBuffEntryModelMaster Create a new Buff Entry Model Master Creates a new Buff Entry Model Master that defines a buff effect applicable to game data. You can configure the name, application method (Rate Add, Mul, Value Add), target type (model or action), target details, priority, and optionally associate it with a GS2-Schedule event to limit the buff to a specific period. Buffs with smaller priority values are evaluated first when multiple buffs apply to the same target. Changes do not take effect until the master data is activated (published) via the Current Buff Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Rate Add “mul” Mul “value_add” Value Add targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff Result Type Description item BuffEntryModelMaster Buff Entry Model Master created Implementation Example getBuffEntryModelMaster Get Buff Entry Model Master Retrieves a specific Buff Entry Model Master by name in the specified namespace. The retrieved information includes the application method, target type, target details, priority, metadata, and the associated GS2-Schedule event if configured. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). buffEntryName string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BuffEntryModelMaster Buff Entry Model Master Implementation Example updateBuffEntryModelMaster Update Buff Entry Model Master Updates the specified Buff Entry Model Master. You can change the description, metadata, application method (Rate Add, Mul, Value Add), target type, target details, priority, and the associated GS2-Schedule event. Changes do not take effect until the master data is activated (published) via the Current Buff Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). buffEntryName string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Rate Add “mul” Mul “value_add” Value Add targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff Result Type Description item BuffEntryModelMaster Buff Entry Model Master updated Implementation Example deleteBuffEntryModelMaster Delete Buff Entry Model Master Deletes the specified Buff Entry Model Master from the specified namespace. Once deleted, this buff entry will no longer be available after the next master data activation. This operation only affects the master data; the currently active model remains unchanged until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). buffEntryName string  ~ 128 chars Buff Entry Model name Buff Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BuffEntryModelMaster Buff Entry Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Buff SDK for various programming languages\n","title":"GS2-Buff SDK API Reference","url":"/api_reference/buff/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed within the chat service. allowCreateRoom bool true Whether to allow game players to create rooms If the game operator pre-creates rooms and players subscribe to them, specify “false”. On the other hand, if the game player creates the rooms freely and invites other players to play, specify “true”. messageLifeTimeDays int 1 1 ~ 30 Message retention period (days) The number of days to keep messages in the room. postMessageScript ScriptSetting Script to run when you post a message Script Trigger Reference - postMessage createRoomScript ScriptSetting Script to run when a room is created Script Trigger Reference - createRoom deleteRoomScript ScriptSetting Script to run when a room is deleted Script Trigger Reference - deleteRoom subscribeRoomScript ScriptSetting Script to run when a room is subscribed Script Trigger Reference - subscribeRoom unsubscribeRoomScript ScriptSetting Script to run when a room is unsubscribed Script Trigger Reference - unsubscribeRoom postNotification NotificationSetting  Push notifications when new posts come to the rooms to which you are subscribed Configuration for sending push notifications via GS2-Gateway when a new message is posted to a subscribed room. Without this setting, clients must poll rooms to detect new messages. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log Namespace information used to output log data. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway Namespace to use for push notifications Specify the GS2-Gateway Namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Room Room A room represents the scope within which chat messages can be delivered. GS2-Chat rooms do not have the concept of participation. Therefore, to receive messages, it is sufficient to know the room name, and there is no need to join the room or register as a member. If you wish to limit the number of game players who can view the messages in a room, there are two options. The first is to set a password for the room. Second, you can whitelist the room and limit the game players by setting their user IDs in the whitelist. Note that if you set a password, even the game administrator will not be able to retrieve messages without knowing the password. This is because this may fall under the secret of communication stipulated in the Constitution of Japan. If you subscribe to a room, you can receive GS2-Gateway push notifications when new messages are sent to the room. By using this notification function, you will be able to know if there are any new messages without polling the room. Details  roomId string * ~ 1024 chars Room A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars Owner User ID The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Message Message Messages are data posted to a room. It has a field called category, which allows classification of messages. For example, a category of 0 is interpreted as a normal text message, while a category of 1 can be processed as a stamp (sticker). Messages posted will be automatically deleted after the message retention period set in the Chat Namespace’s messageLifeTimeDays setting has elapsed. Details  messageId string * ~ 1024 chars Message A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. userId string  ~ 128 chars User ID category int 0 0 ~ 2147483645 Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. metadata string  ~ 1024 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Subscribe Room Subscription By subscribing to a room, you will be instantly informed of new Messages for that room. When subscribing, you can specify the category of the message. This feature can be used to subscribe only to Messages that are of high importance to you. Details  subscribeId string * ~ 1024 chars Subscription A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision CategoryModel Category Model Category Model defines the categories used to classify messages posted in chat rooms. Each category is identified by a numeric value, and you can configure whether posts using player access tokens are allowed or rejected per category. This enables use cases such as system-only announcement categories where only the server can post messages. Details  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens NotificationType Notification Type Configuration of categories for receiving new message notifications Details  category int 0 0 ~ 2147483646 Categories for which you receive new message notifications The numeric category identifier to filter notifications. Only messages matching this category will trigger a push notification for the subscription. enableTransferMobilePushNotification bool false Whether to forward to mobile push notifications when offline When enabled, if the recipient device is offline at the time of notification, the notification is forwarded to the mobile push notification service. This allows players to be notified of new messages even when the game is not running. CurrentModelMaster Currently active Category Model master data This master data defines the Category Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Chat Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master data CategoryModelMaster Category Model Master Category Model Master is data used to edit and manage Category Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Category Model actually referenced by the game. Category Model is the setting for the categories to be posted in the room. Details  categoryModelId string * ~ 1024 chars Category Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. description string ~ 1024 chars Description rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed within the chat service. allowCreateRoom bool true Whether to allow game players to create rooms If the game operator pre-creates rooms and players subscribe to them, specify “false”. On the other hand, if the game player creates the rooms freely and invites other players to play, specify “true”. messageLifeTimeDays int 1 1 ~ 30 Message retention period (days) The number of days to keep messages in the room. postMessageScript ScriptSetting Script to run when you post a message Script Trigger Reference - postMessage createRoomScript ScriptSetting Script to run when a room is created Script Trigger Reference - createRoom deleteRoomScript ScriptSetting Script to run when a room is deleted Script Trigger Reference - deleteRoom subscribeRoomScript ScriptSetting Script to run when a room is subscribed Script Trigger Reference - subscribeRoom unsubscribeRoomScript ScriptSetting Script to run when a room is unsubscribed Script Trigger Reference - unsubscribeRoom postNotification NotificationSetting  Push notifications when new posts come to the rooms to which you are subscribed Configuration for sending push notifications via GS2-Gateway when a new message is posted to a subscribed room. Without this setting, clients must poll rooms to detect new messages. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log Namespace information used to output log data. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed within the chat service. allowCreateRoom bool true Whether to allow game players to create rooms If the game operator pre-creates rooms and players subscribe to them, specify “false”. On the other hand, if the game player creates the rooms freely and invites other players to play, specify “true”. messageLifeTimeDays int 1 1 ~ 30 Message retention period (days) The number of days to keep messages in the room. postMessageScript ScriptSetting Script to run when you post a message Script Trigger Reference - postMessage createRoomScript ScriptSetting Script to run when a room is created Script Trigger Reference - createRoom deleteRoomScript ScriptSetting Script to run when a room is deleted Script Trigger Reference - deleteRoom subscribeRoomScript ScriptSetting Script to run when a room is subscribed Script Trigger Reference - subscribeRoom unsubscribeRoomScript ScriptSetting Script to run when a room is unsubscribed Script Trigger Reference - unsubscribeRoom postNotification NotificationSetting  Push notifications when new posts come to the rooms to which you are subscribed Configuration for sending push notifications via GS2-Gateway when a new message is posted to a subscribed room. Without this setting, clients must poll rooms to detect new messages. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log Namespace information used to output log data. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeRooms Get a list of Room Information You can get a list of Room Information by specifying a page token and a limit on the number of acquisitions. This allows you to check the overview of existing rooms. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Room Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRoom Create Room You can create a room by specifying a room name, user ID, metadata, password, and user ID to be registered in the whitelist. The room name is optional, and if omitted, a UUID (Universally Unique Identifier) will be automatically assigned. It is used to create a new communication space. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. name string UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). Result Type Description item Room Room created Implementation Example createRoomFromBackend Create Room from Backend This API is not called by game players, but is used when creating rooms related to the system. You can create a room by specifying a room name, user ID, metadata, password, and user ID to be registered in the whitelist. The room name is optional, and if omitted, a UUID (Universally Unique Identifier) will be automatically assigned. It is used to create a new communication space. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars Owner User ID The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Room Room created Implementation Example getRoom Get Room Information Retrieves detailed information about a specific room by name in the specified namespace. The retrieved information includes the room’s metadata, the user ID of the creator, and whitelist settings. No password validation is required for this operation; the password is not exposed in the response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Room Room Implementation Example updateRoom Update Room Updates the specified room’s metadata, password, and whitelist settings. Only the room creator (the user who originally created the room) or a user listed in the whitelist can perform this operation. An error is returned if the currently logged-in user does not have write permission on the room. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). accessToken string ~ 128 chars Access token The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. Result Type Description item Room Rooms updated Implementation Example updateRoomFromBackend Update Room from Backend Updates the specified room’s metadata, password, and whitelist settings from the server side. Unlike the player-facing update API, this does not validate write permission against the access token, as it is intended for system-level operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. whiteListUserIds List [] 0 ~ 1000 items List of user IDs with access to the room When set, only the listed users can retrieve and post messages in the room. If empty, access is not restricted by user ID (though a password may still be required). userId string ~ 128 chars Owner User ID The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Room Rooms updated Implementation Example deleteRoom Delete Room Deletes the specified room from the namespace. Only the room creator or a user listed in the whitelist can perform this operation. An error is returned if the currently logged-in user does not have write permission on the room. Deleting a room removes all messages and subscription information associated with it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. Result Type Description item Room Room deleted Implementation Example deleteRoomFromBackend Delete Room from Backend Deletes the specified room from the server side. Unlike the player-facing delete API, this does not validate write permission against the access token, as it is intended for system-level operations. Deleting a room removes all messages and subscription information associated with it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars Owner User ID The user ID of the room owner. When set, only the owner can delete the room. Setting an owner is optional. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Room Room deleted Implementation Example describeMessages Get a list of messages Retrieves messages in the specified room, ordered chronologically from the specified start time to the current time. You can optionally filter by category number to retrieve only specific types of messages (e.g., text messages, stamps). If a password is set for the room, the correct password must be provided. If the room has a whitelist configured, access is restricted to listed users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. category int 0 ~ 2147483645 Type number when you want to classify message types. accessToken string  ~ 128 chars Access token startAt long The absolute time 1 hour prior to the current time Start time for message retrieval Unix time, milliseconds limit int 30 1 ~ 1000 Number of data items to retrieve Result Type Description items List List of Message Implementation Example describeMessagesByUserId Get a list of Messages by specifying a user ID Retrieves messages in the specified room, ordered chronologically from the specified start time to the current time. You can optionally filter by category number to retrieve only specific types of messages (e.g., text messages, stamps). If a password is set for the room, the correct password must be provided. If the room has a whitelist configured, access is restricted to listed users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. category int 0 ~ 2147483645 Type number when you want to classify message types. userId string  ~ 128 chars User ID startAt long The absolute time 1 hour prior to the current time Start time for message retrieval Unix time, milliseconds limit int 30 1 ~ 1000 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Message Implementation Example describeLatestMessages Get a list of latest Messages Retrieves the newest messages in the specified room with pagination support, ordered from newest to oldest. This is useful for displaying a chat timeline where the most recent messages are shown first. You can optionally filter by category number to retrieve only specific types of messages. If a password is set for the room, the correct password must be provided. If the room has a whitelist configured, access is restricted to listed users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. category int 0 ~ 2147483645 Type number when you want to classify message types. accessToken string  ~ 128 chars Access token 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 List of Message nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeLatestMessagesByUserId Get a list of latest Messages by specifying a user ID Retrieves the newest messages in the specified room with pagination support, ordered from newest to oldest. This is useful for displaying a chat timeline where the most recent messages are shown first. You can optionally filter by category number to retrieve only specific types of messages. If a password is set for the room, the correct password must be provided. If the room has a whitelist configured, access is restricted to listed users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  UUID ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). password string ~ 128 chars Password required to access the room When set, the password must be provided to retrieve or post messages. The password value cannot be referenced again after setting. Even game administrators cannot access messages without the password, as this may fall under communication privacy protections. category int 0 ~ 2147483645 Type number when you want to classify message types. userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Message nextPageToken string Page token to retrieve the rest of the listing Implementation Example post Post a message Posts a message to the specified room as the currently logged-in user. You can specify a category number to classify the message type (e.g., 0 for text, 1 for stamp/sticker) and metadata containing the message content. If the category has the rejectAccessTokenPost flag enabled in its Category Model, posting via access token is rejected and an error is returned. In that case, use the server-side PostByUserId API instead. If a password is set for the room, the correct password must be provided. If the room has a whitelist, access is restricted to listed users. After posting, notifications are automatically sent to all users subscribed to the room who match the message’s category notification setting. The message TTL is determined by the namespace’s messageLifeTimeDays setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token category int 0 0 ~ 2147483645 Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. metadata string  ~ 1024 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. password string ~ 128 chars Password Result Type Description item Message Posted message Implementation Example postByUserId Post a Message by specifying a user ID Posts a message to the specified room as the specified user from the server side. Unlike the access-token-based post, this API is not subject to the rejectAccessTokenPost restriction on categories, making it suitable for posting system messages and announcements. If a password is set for the room, the correct password must be provided. If the room has a whitelist, access is restricted to listed users. After posting, notifications are automatically sent to all users subscribed to the room who match the message’s category notification setting. The message TTL is determined by the namespace’s messageLifeTimeDays setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID category int 0 0 ~ 2147483645 Type number when you want to classify message types. A numeric value used to classify messages. For example, 0 can represent text messages, 1 can represent stamps/stickers, and other values can represent custom message types. The category determines which CategoryModel rules apply to the message. metadata string  ~ 1024 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. password string ~ 128 chars Password timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Posted message Implementation Example getMessage Get Message Retrieves a specific message by name from the specified room. If a password is set for the room, the correct password must be provided. If the room has a whitelist, access is restricted to listed users. The retrieved information includes the message category, metadata (content), the posting user ID, and the creation timestamp. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. password string ~ 128 chars Password accessToken string ~ 128 chars Access token Result Type Description item Message Message Implementation Example getMessageByUserId Get Message by specifying a user ID Retrieves a specific message by name from the specified room using a server-side user ID. If a password is set for the room, the correct password must be provided. If the room has a whitelist, access is restricted to listed users. The retrieved information includes the message category, metadata (content), the posting user ID, and the creation timestamp. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. password string ~ 128 chars Password userId string ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message Implementation Example deleteMessage Delete message Deletes a specific message from the specified room. This operation permanently removes the message and it cannot be recovered. This is a management API that can delete any message regardless of the posting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room Name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message deleted Implementation Example describeSubscribes Get a list of Room Subscriptions You can get a list of subscriptions by specifying a page token and a limit on the number of acquisitions. This allows you to check an overview of the rooms that the user is subscribed to. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomNamePrefix string ~ 64 chars Filter by Room name prefix accessToken string  ~ 128 chars Access token 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 List of Room Subscriptions nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSubscribesByUserId Get a list of Room Subscriptions by specifying a user ID You can get a list of subscriptions by specifying a page token and a limit on the number of acquisitions. This allows you to check an overview of the rooms that the user is subscribed to. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomNamePrefix string ~ 64 chars Filter by Room name prefix userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Room Subscriptions nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSubscribesByRoomName Get a list of users subscribed to a room by specifying Room name You can get a list of users subscribed to a room by specifying a page token and a limit on the number of acquisitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. 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 List of Room Subscriptions nextPageToken string Page token to retrieve the rest of the listing Implementation Example subscribe Subscribe to a room Subscribes the currently logged-in user to receive notifications when new messages are posted to the specified room. You can configure notification preferences by specifying notification types, which allow filtering notifications by message category. When a message is posted to the subscribed room, notifications are distributed to all subscribers whose category filters match. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. accessToken string  ~ 128 chars Access token notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. Result Type Description item Subscribe Room Subscription Implementation Example subscribeByUserId Subscribe to a room by specifying a user ID Subscribes the specified user to receive notifications when new messages are posted to the specified room. You can configure notification preferences by specifying notification types, which allow filtering notifications by message category. When a message is posted to the subscribed room, notifications are distributed to all subscribers whose category filters match. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. userId string  ~ 128 chars User ID notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Subscribe Room Subscription Implementation Example getSubscribe Get Room Subscription Retrieves the subscription information for the currently logged-in user to the specified room. The returned information includes the configured notification type preferences for this subscription. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. accessToken string  ~ 128 chars Access token Result Type Description item Subscribe Room Subscription Implementation Example getSubscribeByUserId Get Room Subscription by specifying a user ID Retrieves the subscription information for the specified user to the specified room. The returned information includes the configured notification type preferences for this subscription. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Subscribe Room Subscription Implementation Example updateNotificationType Update notification methods Updates the notification type preferences for the currently logged-in user’s subscription to the specified room. By configuring notification types, you can control which message categories trigger push notifications for the user. For example, you can set the subscription to only receive notifications for certain category numbers, or disable notifications for specific categories. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. accessToken string  ~ 128 chars Access token notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. Result Type Description item Subscribe Renewed Subscriptions Implementation Example updateNotificationTypeByUserId Update notification methods by specifying a user ID Updates the notification type preferences for the specified user’s subscription to the specified room. By configuring notification types, you can control which message categories trigger push notifications for the user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. userId string  ~ 128 chars User ID notificationTypes List [] 0 ~ 100 items List of categories to receive notifications of new Messages Filters which message categories trigger push notifications. If empty, notifications are sent for all categories. Each entry specifies a category number and optional mobile push notification forwarding. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Subscribe Renewed Subscriptions Implementation Example unsubscribe Unsubscribe from a room Removes the currently logged-in user’s subscription to the specified room. After unsubscribing, the user will no longer receive notifications when new messages are posted to this room. The subscription record is permanently deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. accessToken string  ~ 128 chars Access token Result Type Description item Subscribe Unsubscribed room subscription Implementation Example unsubscribeByUserId Unsubscribe from a subscription by specifying a user ID Removes the specified user’s subscription to the specified room. After unsubscribing, the user will no longer receive notifications when new messages are posted to this room. The subscription record is permanently deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name to subscribe to The name of the chat room to subscribe to. When subscribed, push notifications are sent via GS2-Gateway whenever new messages are posted to this room. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Subscribe Unsubscribed room subscription Implementation Example describeCategoryModels Get a list of Category Models Retrieves all currently active Category Models in the specified namespace. Category Models define message categories (e.g., normal text messages, stamps/stickers) and control posting permissions per category. Unlike the master variant, this returns only the activated (published) models without pagination. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Models Implementation Example getCategoryModel Get Category Model Retrieves the currently active Category Model with the specified category number in the specified namespace. The retrieved information includes whether access-token-authenticated users are restricted from posting to this category (rejectAccessTokenPost flag). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. Result Type Description item CategoryModel Category Model Implementation Example exportMaster Export Category Model Master in a master data format that can be activated Exports the current Category Model Master data in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Category Model master data that can be activated Implementation Example getCurrentModelMaster Get currently active Category Model master data Retrieves the master data of the Category Models that are currently active (published) in the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Currently active Category Model master data Implementation Example preUpdateCurrentModelMaster Update currently active Category Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentModelMaster Update currently active Category Model master data Updates and activates (publishes) the master data of the Category Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentModelMaster Updated master data of the currently active Category Models Implementation Example updateCurrentModelMasterFromGitHub Update currently active Category Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentModelMaster Updated master data of the currently active Category Models Implementation Example describeCategoryModelMasters Get a list of Category Model Masters Retrieves a paginated list of Category Model Masters in the specified namespace. Category Model Masters are the editable versions of Category Models that define message categories and their posting permissions. Changes to master data do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Category Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createCategoryModelMaster Create a new Category Model Master Creates a new Category Model Master that defines a message category and its posting permissions. You can configure the category number, description, and the rejectAccessTokenPost flag which controls whether access-token-authenticated users (game players) are allowed to post messages in this category. When rejectAccessTokenPost is enabled, only server-side (userId-based) posting is allowed for this category, which is useful for system messages or announcements. Changes do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. description string ~ 1024 chars Description rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens Result Type Description item CategoryModelMaster Category Model Master created Implementation Example getCategoryModelMaster Get Category Model Master Retrieves a specific Category Model Master by category number in the specified namespace. The retrieved information includes the description and the rejectAccessTokenPost flag for editing purposes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. Result Type Description item CategoryModelMaster Category Model Master Implementation Example updateCategoryModelMaster Update Category Model Master Updates the specified Category Model Master. You can change the description and the rejectAccessTokenPost flag that controls whether access-token-authenticated users can post to this category. Changes do not take effect until the master data is activated (published) via the Current Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. description string ~ 1024 chars Description rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens Result Type Description item CategoryModelMaster Category Model Master updated Implementation Example deleteCategoryModelMaster Delete Category Model Master Deletes the specified Category Model Master from the specified namespace. Once deleted, this category will no longer be available after the next master data activation. This operation only affects the master data; the currently active model remains unchanged until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. Result Type Description item CategoryModelMaster Category Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Chat SDK for various programming languages\n","title":"GS2-Chat SDK API Reference","url":"/api_reference/chat/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing datastore operations. Supports auto-run, atomic commit, and async processing options. doneUploadScript ScriptSetting Script setting executed on upload completion (doneUpload event) Script Trigger Reference - doneUpload logSetting LogSetting Log Output Setting Configuration for outputting log data of datastore operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for data object uploads, downloads, and access control changes can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. DataObject Data Object Data objects are data uploaded by game players. Data is generation managed, with 30 days of historical data stored. Access permissions can be set for the data. There are three types of scopes: public : Accessible to anyone protected : Accessible only to game players with specified user IDs private : Accessible only to yourself Details  dataObjectId string * ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. userId string  ~ 128 chars User ID scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” status string (enum) enum {   “ACTIVE”,   “UPLOADING”,   “DELETED” }  Status The current lifecycle state of the data object. ACTIVE indicates the data is available for access, UPLOADING indicates a new version is being uploaded, and DELETED indicates the object has been marked for deletion (actual removal occurs 30 days later). Definition Description “ACTIVE” Active “UPLOADING” Uploading “DELETED” Deleted (Actual deletion 30 days after the deletion process) generation string ~ 128 chars Data Generation An identifier representing the current version of the uploaded data. Each time data is re-uploaded, a new generation ID is assigned. previousGeneration string ~ 128 chars Generation of previously valid data The generation ID of the data version that was active before the current upload. During an upload (UPLOADING status), the previous generation remains accessible to ensure continuous data availability until the new upload completes. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision DataObjectHistory Data Object History You can check the update history of Data Objects. Each time a data object is re-uploaded, a history record is created containing the generation ID and file size. Historical data is retained for 30 days, allowing rollback and audit of previous versions. Details  dataObjectHistoryId string * ~ 1024 chars Data Object History A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. generation string  ~ 128 chars Generation ID A unique identifier for the specific version of the data object at the time of upload. Corresponds to the generation field in the DataObject and can be used with PrepareDownloadByGeneration to download this specific version. contentLength long  0 ~ 10485760 File size The size of the uploaded data in bytes for this generation. Maximum file size is 10 MB (10,485,760 bytes). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing datastore operations. Supports auto-run, atomic commit, and async processing options. logSetting LogSetting Log Output Setting Configuration for outputting log data of datastore operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for data object uploads, downloads, and access control changes can be collected. doneUploadScript ScriptSetting Script setting executed on upload completion (doneUpload event) Script Trigger Reference - doneUpload Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing datastore operations. Supports auto-run, atomic commit, and async processing options. logSetting LogSetting Log Output Setting Configuration for outputting log data of datastore operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for data object uploads, downloads, and access control changes can be collected. doneUploadScript ScriptSetting Script setting executed on upload completion (doneUpload event) Script Trigger Reference - doneUpload Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeDataObjects Get a list of Data Objects Retrieves a paginated list of data objects owned by the currently logged-in user in the specified namespace. You can optionally filter by status (ACTIVE, UPLOADING, DELETED) to retrieve only objects in a specific state. If no status filter is specified, all data objects regardless of status are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token status string (enum) enum {   “ACTIVE”,   “UPLOADING”,   “DELETED” } Status Definition Description “ACTIVE” Active “UPLOADING” Uploading “DELETED” Deleted(Actual deletion 30 days after the deletion process) 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 List of Data object nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeDataObjectsByUserId Get a list of Data Objects by specifying a user ID Retrieves a paginated list of data objects owned by the specified user in the specified namespace. You can optionally filter by status (ACTIVE, UPLOADING, DELETED) to retrieve only objects in a specific state. If no status filter is specified, all data objects regardless of status are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID status string (enum) enum {   “ACTIVE”,   “UPLOADING”,   “DELETED” } Status Definition Description “ACTIVE” Active “UPLOADING” Uploading “DELETED” Deleted(Actual deletion 30 days after the deletion process) 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Data object nextPageToken string Page token to retrieve the rest of the listing Implementation Example prepareUpload Prepare to upload data objects Creates a new data object and generates a presigned cloud storage URL for uploading the file. The data object name is optional; if omitted, a UUID is automatically assigned. You can configure the access scope (public/private) and specify a list of user IDs allowed to access the object. If updateIfExists is true and an object with the same name already exists, the existing object’s scope and permissions are updated and a re-upload URL is generated instead of returning an error. The returned presigned URL should be used to PUT the file data directly. After uploading, call DoneUpload to finalize the data object. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token name string ~ 128 chars Data Object Name If not specified, a UUID is automatically assigned. contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data to be uploaded scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” updateIfExists bool false Whether to raise an error if data already exists or to update the data Result Type Description item DataObject Data object uploadUrl string URL used to execute the upload process Implementation Example prepareUploadByUserId Prepare to upload a data object by specifying a user ID Creates a new data object for the specified user and generates a presigned cloud storage URL for uploading the file. The data object name is optional; if omitted, a UUID is automatically assigned. You can configure the access scope (public/private) and specify a list of user IDs allowed to access the object. If updateIfExists is true and an object with the same name already exists, the existing object’s scope and permissions are updated and a re-upload URL is generated instead of returning an error. The returned presigned URL should be used to PUT the file data directly. After uploading, call DoneUpload to finalize the data object. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID name string ~ 128 chars Data Object Name If not specified, a UUID is automatically assigned. contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data to be uploaded scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” updateIfExists bool false Whether to raise an error if data already exists or to update the data timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object uploadUrl string URL used to execute the upload process Implementation Example updateDataObject Update data objects Updates the metadata of an existing data object owned by the currently logged-in user. You can change the access scope (public/private) and the list of user IDs allowed to access the object. This operation only updates the access control settings; the file content itself is not modified. To update the file content, use PrepareReUpload instead. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. accessToken string  ~ 128 chars Access token scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” Result Type Description item DataObject Data object Implementation Example updateDataObjectByUserId Update Data Object by specifying a user ID Updates the metadata of an existing data object owned by the specified user. You can change the access scope (public/private) and the list of user IDs allowed to access the object. This operation only updates the access control settings; the file content itself is not modified. To update the file content, use PrepareReUpload instead. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. userId string  ~ 128 chars User ID scope string (enum) enum {   “public”,   “protected”,   “private” } “private” File access permission Controls who can access this data object. public allows anyone to access, protected restricts access to specified user IDs listed in allowUserIds, and private limits access to the owner only. Definition Description “public” Public “protected” Only to specified users “private” Private allowUserIds List {scope} == “protected” [] 0 ~ 100 items List of user IDs to be published Specifies which users can access this data object when the scope is set to protected . Only users whose IDs are included in this list will be granted read access. * Enabled only if scope is “protected” timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object Implementation Example prepareReUpload Prepare to re-upload data object Generates a new presigned cloud storage URL for re-uploading file content to an existing data object. The data object’s status is changed to UPLOADING and a new generation number is assigned. The previous version of the file is retained in the data object history, allowing you to download older versions by generation number. After uploading the new file to the returned URL, call DoneUpload to finalize the update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. accessToken string  ~ 128 chars Access token contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data object to be uploaded Result Type Description item DataObject Data object uploadUrl string URL used to execute the upload process Implementation Example prepareReUploadByUserId Prepare to re-upload data object by specifying a user ID Generates a new presigned cloud storage URL for re-uploading file content to an existing data object owned by the specified user. The data object’s status is changed to UPLOADING and a new generation number is assigned. The previous version of the file is retained in the data object history. After uploading the new file to the returned URL, call DoneUpload to finalize the update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. userId string  ~ 128 chars User ID contentType string “application/octet-stream” ~ 256 chars MIME-Type of the data object to be uploaded timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object uploadUrl string URL used to execute the upload process Implementation Example doneUpload Report completion of data object upload Finalizes the data object after the file has been uploaded to the presigned URL obtained from PrepareUpload or PrepareReUpload. The data object’s status is changed from UPLOADING to ACTIVE, and the file metadata (size, generation) is recorded. If a doneUploadScript is configured in the namespace settings, the script is executed as a hook after the upload is confirmed. An error is returned if the data object is not in the UPLOADING state or if the uploaded file was not found. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. accessToken string  ~ 128 chars Access token Result Type Description item DataObject Data object Implementation Example doneUploadByUserId Report completion of data object upload by specifying a user ID Finalizes the data object after the file has been uploaded to the presigned URL obtained from PrepareUpload or PrepareReUpload. The data object’s status is changed from UPLOADING to ACTIVE, and the file metadata (size, generation) is recorded. If a doneUploadScript is configured in the namespace settings, the script is executed as a hook after the upload is confirmed. An error is returned if the data object is not in the UPLOADING state or if the uploaded file was not found. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object Implementation Example deleteDataObject Delete data object Marks the specified data object for deletion. The data object owned by the currently logged-in user is targeted. The actual file data is deleted after 30 days. An error is returned if the data object is not in a deletable state (e.g., currently uploading). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. Result Type Description item DataObject Data object Implementation Example deleteDataObjectByUserId Delete a data object by specifying a user ID Marks the specified data object owned by the specified user for deletion. The actual file data is deleted after 30 days. An error is returned if the data object is not in a deletable state (e.g., currently uploading). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object Implementation Example prepareDownload Prepare data object for download Generates a presigned cloud storage URL for downloading the latest version of the specified data object. The data object is specified by its GRN (dataObjectId). Access control is enforced: only the data owner or users listed in allowUserIds can download. Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByUserId Prepare data object for download by specifying a user ID Generates a presigned cloud storage URL for downloading the latest version of the specified data object. The data object is specified by its GRN (dataObjectId). Access control is enforced: only the data owner or users listed in allowUserIds can download. Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByGeneration Prepare data object for download by specifying the generation Generates a presigned cloud storage URL for downloading a specific version (generation) of the data object. This allows you to access previous versions of a file that were retained when the data was re-uploaded. Access control is enforced: only the data owner or users listed in allowUserIds can download. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN generation string  ~ 128 chars Data Generation Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByGenerationAndUserId Prepare data object for download by specifying user ID and generation Generates a presigned cloud storage URL for downloading a specific version (generation) of the data object. This allows you to access previous versions of a file that were retained when the data was re-uploaded. Access control is enforced: only the data owner or users listed in allowUserIds can download. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN generation string  ~ 128 chars Data Generation timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadOwnData Prepare own data object for download by name A convenience API for downloading the currently logged-in user’s own data object by specifying its name instead of its GRN (dataObjectId). Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByUserIdAndDataObjectName Prepare data object for download by specifying user ID and object name A convenience API for downloading a user’s data object by specifying the user ID and object name instead of the GRN (dataObjectId). Access control is enforced: only the data owner or users listed in allowUserIds can download. Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadOwnDataByGeneration Prepare own data object for download by specifying the generation A convenience API for downloading a specific version (generation) of the currently logged-in user’s own data object by specifying its name instead of its GRN. This allows you to access previous versions of a file that were retained when the data was re-uploaded. Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. generation string  ~ 128 chars Data Generation Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example prepareDownloadByUserIdAndDataObjectNameAndGeneration Prepare data object for download by specifying user ID, object name, and generation A convenience API for downloading a specific version (generation) of a user’s data object by specifying the user ID and object name instead of the GRN. This allows you to access previous versions of a file that were retained when the data was re-uploaded. Access control is enforced: only the data owner or users listed in allowUserIds can download. Returns the presigned download URL and the file size (content length). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. generation string  ~ 128 chars Data Generation timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObject Data object fileUrl string URL to download the file contentLength long File size Implementation Example restoreDataObject Repair management information on data objects Reconciles the stored metadata of a data object with the actual file state. If the recorded generation number or content length differs from the actual file, the metadata is updated to match. This is useful for recovering from inconsistencies that may occur due to partial failures during upload. Only data objects with ACTIVE status can be restored; an error is returned for other statuses. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dataObjectId string  ~ 1024 chars Data object A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item DataObject Data object Implementation Example describeDataObjectHistories Get a list of Data Object Histories Lists all version histories (generations) of a specific data object owned by the currently logged-in user. Each time a data object’s file content is re-uploaded via PrepareReUpload and DoneUpload, a new generation is created and the previous version is recorded in the history. The history entries contain metadata about each generation, such as the content length and creation timestamp. Results can be paginated using a page token and limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. 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 List of Data Object Histories nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeDataObjectHistoriesByUserId Get a list of Data Object Histories by specifying a user ID Lists all version histories (generations) of a specific data object owned by the specified user. Each time a data object’s file content is re-uploaded via PrepareReUpload and DoneUpload, a new generation is created and the previous version is recorded in the history. The history entries contain metadata about each generation, such as the content length and creation timestamp. Results can be paginated using a page token and limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Data Object Histories nextPageToken string Page token to retrieve the rest of the listing Implementation Example getDataObjectHistory Get Data Object History Retrieves the history entry for a specific generation of a data object owned by the currently logged-in user. By specifying the generation number, you can access metadata about a particular version of the data object, including its content length and creation timestamp. This is useful for inspecting past versions of the data object before downloading them via PrepareDownloadByGeneration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. generation string  ~ 128 chars Generation ID A unique identifier for the specific version of the data object at the time of upload. Corresponds to the generation field in the DataObject and can be used with PrepareDownloadByGeneration to download this specific version. Result Type Description item DataObjectHistory Data Object History Implementation Example getDataObjectHistoryByUserId Get Data Object History by specifying a user ID Retrieves the history entry for a specific generation of a data object owned by the specified user. By specifying the generation number, you can access metadata about a particular version of the data object, including its content length and creation timestamp. This is useful for inspecting past versions of the data object before downloading them via PrepareDownloadByGeneration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID dataObjectName string  UUID ~ 128 chars Data Object Name A unique name identifying the data object. Automatically generated in UUID format by default. Used to reference and manage the uploaded data within the namespace. generation string  ~ 128 chars Generation ID A unique identifier for the specific version of the data object at the time of upload. Corresponds to the generation field in the DataObject and can be used with PrepareDownloadByGeneration to download this specific version. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item DataObjectHistory Data Object History Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Datastore SDK for various programming languages\n","title":"GS2-Datastore SDK API Reference","url":"/api_reference/datastore/sdk/"},{"content":"Models GitHubCheckoutSetting Setting for checking out master data from GitHub Configuration for fetching template or master data files directly from a GitHub repository. Supports referencing by commit hash, branch name, or tag name, and requires a GS2-Key GitHub API key for authentication. Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name The GitHub repository name in “owner/repo” format from which to fetch the file. sourcePath string  ~ 1024 chars Master data (JSON) file path The file path within the repository to the target file. For example, “data/master.json” or “deploy/template.yaml”. referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code The type of Git reference to use for checking out the file. commit_hash fetches from a specific commit for reproducibility, branch fetches the latest from a branch, and tag fetches from a tagged release. Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash The full Git commit SHA to check out. Ensures the exact same version of the file is always fetched, providing deployment reproducibility. * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name The Git branch name to check out from. The latest commit on this branch will be used to fetch the file. * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name The Git tag name to check out from. Tags are typically used to mark release versions, providing a stable reference point for deployment. * Required if referenceType is “tag” Resource Resource Resources represent individual GS2 service entities managed by a stack. Each resource corresponds to a GS2 API resource (such as a namespace or model) defined in the stack template. Details  resourceId string * ~ 1024 chars Resource A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server type string  ~ 1024 chars Resource Type The GS2 resource type identifier (e.g., “GS2::Inventory::Namespace”, “GS2::Experience::ExperienceModel”). Determines which GS2 API is called for creating, updating, or deleting this resource. name string  ~ 128 chars Resource name The logical name assigned to this resource in the stack template. Used to reference the resource within the template for dependency resolution and output field mappings. request string  ~ 1048576 chars Request parameter The JSON-serialized API request parameters used to create or update this resource. response string  ~ 1048576 chars Response to resource creation/update The JSON-serialized API response returned when the resource was created or updated. Contains the actual resource state including generated IDs and default values. rollbackContext string (enum) enum {   “create”,   “update”,   “delete” } Types of rollback operations The operation type to perform when rolling back this resource. create means the resource was newly created and should be deleted on rollback, update means the resource was modified and should be reverted, delete means the resource was removed and should be recreated. Definition Description “create” Create “update” Update “delete” Delete rollbackRequest string ~ 1048576 chars Request parameters for rollback The JSON-serialized API request parameters to use when rolling back this resource. For updated resources, contains the previous state to restore. For deleted resources, contains the creation parameters to recreate. rollbackAfter List [] 0 ~ 1000 items Name of the resource on which you are relying at the time of rollback List of resource names that must be rolled back before this resource. Ensures rollback operations are executed in the correct dependency order to maintain consistency. outputFields List [] 0 ~ 1000 items Fields to be recorded in Output when the resource is created Specifies which fields from the API response should be extracted and saved as stack outputs. Each entry maps an output name to a field path in the response, enabling other stacks or external systems to reference the created resource’s values. workId string  ~ 1024 chars Execution ID at the time this resource was created A unique identifier for the stack operation (create/update) that provisioned this resource. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Event Event Events are generated to provide information when operations such as creating, updating, or deleting resources in the stack are performed. Developers can monitor how the stack deployment process and resource changes are progressing and take necessary actions. Details  eventId string * ~ 1024 chars Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Event name Maintains a unique name for each event. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each event. resourceName string  ~ 128 chars Resource name The logical name assigned to this resource in the stack template. Used to reference the resource within the template for dependency resolution and output field mappings. type string (enum) enum {   “CREATE_IN_PROGRESS”,   “CREATE_COMPLETE”,   “CREATE_FAILED”,   “UPDATE_IN_PROGRESS”,   “UPDATE_COMPLETE”,   “UPDATE_FAILED”,   “CLEAN_IN_PROGRESS”,   “CLEAN_COMPLETE”,   “CLEAN_FAILED”,   “DELETE_IN_PROGRESS”,   “DELETE_COMPLETE”,   “DELETE_FAILED”,   “ROLLBACK_IN_PROGRESS”,   “ROLLBACK_COMPLETE”,   “ROLLBACK_FAILED” }  Status The type of event indicating the current state of a resource operation. Tracks progress through in-progress, complete, and failed states for create, update, clean, delete, and rollback operations on individual resources. Definition Description “CREATE_IN_PROGRESS” Create in Progress “CREATE_COMPLETE” Create Complete “CREATE_FAILED” Create Failed “UPDATE_IN_PROGRESS” Update in Progress “UPDATE_COMPLETE” Update Complete “UPDATE_FAILED” Update Failed “CLEAN_IN_PROGRESS” Clean in Progress “CLEAN_COMPLETE” Clean Complete “CLEAN_FAILED” Clean Failed “DELETE_IN_PROGRESS” Delete in Progress “DELETE_COMPLETE” Delete Complete “DELETE_FAILED” Delete Failed “ROLLBACK_IN_PROGRESS” Rollback in Progress “ROLLBACK_COMPLETE” Rollback Complete “ROLLBACK_FAILED” Rollback Failed message string ~ 5242880 chars Message A detailed message describing the event. For failed operations, contains the error message explaining why the resource operation failed. For successful operations, may contain additional context about the completed action. eventAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Output Output created by the stack You can create outputs using this model by specifying the data you want to record in the Outputs section of the stack. For example, when creating credentials, the client secret can only be confirmed at the moment of creation, but by recording its value as an output, you can refer to the value of the client secret later. Details  outputId string * ~ 1024 chars Output A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 1024 chars Output Name The logical name of the output as defined in the stack template’s Outputs section. Used to reference this output value from other stacks or external systems. value string ~ 1048576 chars Value The actual output value extracted from the resource’s API response. For example, a client secret or resource ARN that was generated during resource creation and can be referenced later. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Stack Stack A stack is an entity that sets up resources on GS2 using GS2-Deploy. The stack is designed to specify a template file, and the template file defines the resources needed on GS2. When creating or updating a stack, GS2-Deploy detects changes in the template file. It creates new resources if added, updates existing resources if modified, and deletes resources if removed. This mechanism allows resources on GS2 to be described declaratively and managed in a reproducible manner. This reproducibility allows for error-free execution when migrating settings from the development environment to the production environment, for example. Details  stackId string * ~ 1024 chars Stack A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. description string ~ 1024 chars Description template string  ~ 5242880 chars Template data A YAML or JSON document that declaratively defines the GS2 resources to be provisioned. GS2-Deploy detects differences between the current and previous templates to create, update, or delete resources as needed. Maximum size is 5 MB. status string (enum) enum {   “CREATE_PROCESSING”,   “CREATE_COMPLETE”,   “UPDATE_PROCESSING”,   “UPDATE_COMPLETE”,   “CLEAN_PROCESSING”,   “CLEAN_COMPLETE”,   “DELETE_PROCESSING”,   “DELETE_COMPLETE”,   “ROLLBACK_INITIALIZING”,   “ROLLBACK_PROCESSING”,   “ROLLBACK_COMPLETE” } “CREATE_PROCESSING” Execution state The current lifecycle state of the stack operation. Transitions through processing and completion states for create, update, clean (resource removal), delete, and rollback operations. A failed operation may trigger a rollback to restore the previous state. Definition Description “CREATE_PROCESSING” Create Processing “CREATE_COMPLETE” Create Complete “UPDATE_PROCESSING” Update Processing “UPDATE_COMPLETE” Update Complete “CLEAN_PROCESSING” Clean Processing “CLEAN_COMPLETE” Clean Complete “DELETE_PROCESSING” Delete Processing “DELETE_COMPLETE” Delete Complete “ROLLBACK_INITIALIZING” Rollback Initializing “ROLLBACK_PROCESSING” Rollback Processing “ROLLBACK_COMPLETE” Rollback complete createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision OutputField Output field Defines a mapping from a resource’s API response field to a named stack output. Details  name string  ~ 1024 chars Name The output key name under which the extracted value will be stored. This name is used to reference the output value from the stack’s Outputs. fieldName string  ~ 1024 chars Field name The field path in the resource’s API response to extract the value from. Specifies which property of the created or updated resource should be recorded as the output. ChangeSet Change Details Represents a single resource change detected when comparing the current and new stack templates. Used in the validate operation to preview what resources will be created, updated, or deleted before actually executing the stack update. Details  resourceName string  ~ 128 chars Resource name The logical name of the resource as defined in the stack template that will be affected by this change. resourceType string  ~ 128 chars Resource type The GS2 resource type identifier of the resource being changed (e.g., “GS2::Inventory::Namespace”). operation string (enum) enum {   “create”,   “update”,   “delete” }  Change type The type of change to be applied to this resource. create indicates a new resource will be provisioned, update indicates an existing resource will be modified, and delete indicates a resource will be removed. Definition Description “create” Create “update” Update “delete” Delete Methods describeResources Get a list of Resources Retrieves a paginated list of resources that are managed by the specified stack. Each resource represents a GS2 service component (such as a namespace, model, or configuration) that was provisioned by the stack’s template. The resource information includes the type, name, current request body, and associated properties. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. 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 List of Resource nextPageToken string Page token to retrieve the rest of the listing Implementation Example getResource Get Resource Retrieves the detailed information of a specific resource managed by the stack. The resource details include its type, name, request body used for provisioning, and response properties returned after creation. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. resourceName string  ~ 128 chars Resource name The logical name assigned to this resource in the stack template. Used to reference the resource within the template for dependency resolution and output field mappings. Result Type Description item Resource Resource Implementation Example describeEvents Get a list of Events Retrieves a paginated list of events that occurred during stack operations (creation, update, deletion). Events record the progress and outcomes of each resource operation, including the resource type, action taken, and any error messages. This is useful for monitoring the status of ongoing operations or reviewing the history of completed operations. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. 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 List of Event nextPageToken string Page token to retrieve the rest of the listing Implementation Example getEvent Get Event Retrieves the detailed information of a specific event within a stack. The event contains the resource type, action (create/update/delete), status, and any error message that occurred during the operation. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. eventName string  UUID ~ 36 chars Event name Maintains a unique name for each event. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each event. Result Type Description item Event Event Implementation Example describeOutputs Get a list of Outputs Retrieves a paginated list of output values produced by the stack after successful creation or update. Outputs are key-value pairs defined in the template that expose important information such as resource identifiers, endpoints, or configuration values generated during stack provisioning. Outputs are only available when the stack is in a _COMPLETE status. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. 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 List of Output nextPageToken string Page token to retrieve the rest of the listing Implementation Example getOutput Get Output Retrieves a specific output value by name from the stack. The output contains the key name and its corresponding value that was produced during stack provisioning. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. outputName string  ~ 1024 chars Output Name The logical name of the output as defined in the stack template’s Outputs section. Used to reference this output value from other stacks or external systems. Result Type Description item Output Output Implementation Example describeStacks Get a list of Stacks Retrieves a list of stacks with optional filtering by name prefix. You can use pagination with a page token and limit to retrieve the results incrementally. Each stack in the list includes its current status, name, description, and template information. Details Request  namePrefix string ~ 64 chars Filter by Stack name prefix 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 List of Stack nextPageToken string Page token to retrieve the rest of the listing Implementation Example preCreateStack Prepare to create a new Stack (pre-upload) Obtains an upload token and a presigned URL for uploading a template file. When the template exceeds 1MB, this 3-phase flow is required: 1) call this API to get the upload URL, 2) upload the template to the URL, 3) call CreateStack with the upload token in preUpload mode. The presigned URL expires after 60 minutes. Details Request  Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example createStack Create a new Stack Creates a new stack by specifying a name, description, and template. Supports two modes: ‘direct’ mode where the template is passed inline in the request body, and ‘preUpload’ mode where the template was previously uploaded using the PreCreateStack API. The template is validated before the stack is created. If validation fails, an error is returned. After creation, the stack enters the CREATE_PROCESSING status and begins provisioning resources asynchronously. Details Request  name string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. description string ~ 1024 chars Description mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update template string {mode} == “direct”  ~ 5242880 chars Template data A YAML or JSON document that declaratively defines the GS2 resources to be provisioned. GS2-Deploy detects differences between the current and previous templates to create, update, or delete resources as needed. Maximum size is 5 MB. * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item Stack Stack created Implementation Example createStackFromGitHub Create a new Stack from GitHub Creates a new stack by fetching the template directly from a GitHub repository. The checkout settings specify the repository, branch or tag, and file path of the template. The fetched template is validated before the stack is created. This is useful for managing templates in version control and deploying infrastructure directly from the repository. Details Request  name string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. description string ~ 1024 chars Description checkoutSetting GitHubCheckoutSetting  Setup to check out template file from GitHub Result Type Description item Stack Stack created Implementation Example preValidate Prepare to validate Template (pre-upload) Obtains an upload token and a presigned URL for uploading a template file to validate. When the template exceeds 1MB, this 3-phase flow is required: 1) call this API to get the upload URL, 2) upload the template to the URL, 3) call Validate with the upload token in preUpload mode. The presigned URL expires after 60 minutes. Details Request  Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example validate Validate Template Validates the structure and syntax of a template without actually creating or updating a stack. Supports two modes: ‘direct’ mode where the template is passed inline, and ‘preUpload’ mode where the template was previously uploaded using the PreValidate API. Note that this API only performs structural validation. Even if the validation passes, runtime errors may still occur during actual stack creation or update. Details Request  mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update template string {mode} == “direct”  ~ 5242880 chars Template data A YAML or JSON document that declaratively defines the GS2 resources to be provisioned. GS2-Deploy detects differences between the current and previous templates to create, update, or delete resources as needed. Maximum size is 5 MB. * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description Implementation Example getStackStatus Get Stack Status Retrieves only the current status of the specified stack. This API returns only the status string, making it suitable for polling the progress of stack operations. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description status string Implementation Example getStack Get Stack Retrieves the detailed information of the specified stack, including its name, description, template, status, and associated resources. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description item Stack Stack Implementation Example preUpdateStack Prepare to update Stack (pre-upload) Obtains an upload token and a presigned URL for uploading a new template file to update the stack. When the template exceeds 1MB, this 3-phase flow is required: 1) call this API to get the upload URL, 2) upload the template to the URL, 3) call UpdateStack with the upload token in preUpload mode. The presigned URL expires after 60 minutes. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateStack Update Stack Updates an existing stack with a new template and description. The stack must be in a _COMPLETE status (e.g., CREATE_COMPLETE, UPDATE_COMPLETE) to be updated; an error is returned if the stack is still processing. Supports two modes: ‘direct’ mode where the template is passed inline, and ‘preUpload’ mode where the template was previously uploaded using the PreUpdateStack API. The new template is validated before the update begins. After the update starts, the stack enters UPDATE_PROCESSING status and resources are modified asynchronously according to the change set. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. description string ~ 1024 chars Description mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update template string {mode} == “direct”  ~ 5242880 chars Template data A YAML or JSON document that declaratively defines the GS2 resources to be provisioned. GS2-Deploy detects differences between the current and previous templates to create, update, or delete resources as needed. Maximum size is 5 MB. * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item Stack Stack updated Implementation Example preChangeSet Prepare to get Change Set (pre-upload) Obtains an upload token and a presigned URL for uploading a new template file to preview changes. When the template exceeds 1MB, this 3-phase flow is required: 1) call this API to get the upload URL, 2) upload the template to the URL, 3) call ChangeSet with the upload token in preUpload mode. The presigned URL expires after 60 minutes. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example changeSet Get Change Set Compares the current stack template with a new template and returns a list of changes that would be applied. This allows you to preview the impact of an update before actually executing it. Supports two modes: ‘direct’ mode where the template is passed inline, and ‘preUpload’ mode where the template was previously uploaded using the PreChangeSet API. The returned change set lists each resource that would be created, updated, or deleted. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update template string {mode} == “direct”  ~ 5242880 chars Template data A YAML or JSON document that declaratively defines the GS2 resources to be provisioned. GS2-Deploy detects differences between the current and previous templates to create, update, or delete resources as needed. Maximum size is 5 MB. * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description items List List of Stack Implementation Example updateStackFromGitHub Update Stack from GitHub Updates an existing stack by fetching a new template directly from a GitHub repository. The stack must be in a _COMPLETE status to be updated. The checkout settings specify the repository, branch or tag, and file path of the template. The fetched template is validated before the update begins. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. description string ~ 1024 chars Description checkoutSetting GitHubCheckoutSetting  Setup to check out template file from GitHub Result Type Description item Stack Stack updated Implementation Example deleteStack Delete Stack Deletes the resources created by the stack and, if successful, deletes the stack entity. The stack must be in a _COMPLETE status to be deleted. If the stack is already in DELETE_COMPLETE status, only the stack entity is deleted. Otherwise, the stack enters DELETE_PROCESSING status and resource cleanup begins asynchronously. If resource deletion fails for some reason, the stack entity remains so you can retry or use ForceDelete. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description item Stack Stacks deleted Implementation Example forceDeleteStack Force delete Stack Forcibly deletes the stack entity regardless of its current status or whether resources remain. Unlike the normal Delete API, this does not attempt to clean up resources created by the stack. Any remaining resources will be orphaned and must be manually managed. Use this as a last resort when the normal deletion process has failed or the stack is stuck in an unrecoverable state. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description item Stack Stacks deleted Implementation Example deleteStackResources Delete Stack Resources Deletes only the resources created by the stack, while preserving the stack entity and its template. This behaves similarly to updating the stack with an empty template: the stack enters DELETE_PROCESSING status and resource cleanup begins asynchronously. Since the original template remains on the stack entity, you can restore the resources by updating the stack again with the same or a new template. This makes it a safer alternative to full stack deletion in case of mishandling. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description item Stack Stack of deleted resources Implementation Example deleteStackEntity Final Stack Deletion Deletes the stack entity after all resources have been successfully cleaned up. This is typically used after the Delete Stack Resources (Clean) API has completed and the stack is in DELETE_COMPLETE status. An error is returned if the stack still has remaining resources; use the Delete Stack Resources API first to remove them. Details Request  stackName string  ~ 128 chars Stack name A unique name identifying the stack. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Used to reference the stack when performing create, update, or delete operations. Result Type Description item Stack Stacks deleted Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Deploy SDK for various programming languages\n","title":"GS2-Deploy SDK API Reference","url":"/api_reference/deploy/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing dictionary entry registration. Supports auto-run, atomic commit, and async processing options. entryScript ScriptSetting Script setting to be executed when registering an entry Script Trigger Reference - entry duplicateEntryScript string ~ 1024 chars Script GRN to run when an attempt is made to re-register an entry that has already been registered Script Trigger Reference - duplicateEntry logSetting LogSetting Log Output Setting Configuration for outputting log data of dictionary operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for entry registration, like operations, and other dictionary activities can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Entry Entry acquired by game player Represents a single dictionary entry that a game player has collected. Each entry corresponds to an EntryModel and records the acquisition timestamp. The possession state is binary—either the entry exists (collected) or it does not—with no concept of quantity. Details  entryId string * ~ 1024 chars Entry A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string ~ 128 chars User ID name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). acquiredAt long * Current time Date of acquisition The timestamp when this entry was first collected by the game player. Automatically set to the current time at the moment of registration and cannot be modified afterwards. Like Entry registered as a favorite Represents a dictionary entry that a game player has marked as a favorite (liked). Allows players to bookmark specific entries in the dictionary for quick access. Each like references an EntryModel by name and is unique per user—the same entry cannot be liked twice. Details  likeId string * ~ 1024 chars Like Entry A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string ~ 128 chars User ID name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). EntryModel Entry Model An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model. Details  entryModelId string * ~ 1024 chars Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Entry Model name 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. Config Configuration A key-value pair applied to transaction variables during distributed transaction execution. Allows dynamic substitution of placeholder values in transaction parameters at runtime. Details  key string  ~ 64 chars Name The variable name used as the placeholder key in transaction parameters. Must match the placeholder defined in the transaction template. value string ~ 51200 chars Value The value to substitute for the placeholder key at transaction execution time. This value replaces the corresponding placeholder in the transaction parameters. CurrentEntryMaster Currently active Entry Model master data This master data defines the Entry Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Dictionary Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data EntryModelMaster Entry Model Master Entry Model Master is data used to edit and manage entry model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as entry model actually referenced by the game. An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model. Details  entryModelId string * ~ 1024 chars Entry Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing dictionary entry registration. Supports auto-run, atomic commit, and async processing options. entryScript ScriptSetting Script setting to be executed when registering an entry Script Trigger Reference - entry duplicateEntryScript string ~ 1024 chars Script GRN to run when an attempt is made to re-register an entry that has already been registered Script Trigger Reference - duplicateEntry logSetting LogSetting Log Output Setting Configuration for outputting log data of dictionary operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for entry registration, like operations, and other dictionary activities can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing dictionary entry registration. Supports auto-run, atomic commit, and async processing options. entryScript ScriptSetting Script setting to be executed when registering an entry Script Trigger Reference - entry duplicateEntryScript string ~ 1024 chars Script GRN to run when an attempt is made to re-register an entry that has already been registered Script Trigger Reference - duplicateEntry logSetting LogSetting Log Output Setting Configuration for outputting log data of dictionary operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for entry registration, like operations, and other dictionary activities can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeEntries Get a list of Entries Retrieves a paginated list of entries collected by the currently logged-in user. Each entry represents a dictionary item that the user has unlocked or acquired. Use pagination with a page token and limit to retrieve the results incrementally. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 10000 Number of data items to retrieve Result Type Description items List List of Entries nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeEntriesByUserId Get a list of Entries by specifying a user ID Retrieves a paginated list of entries collected by the specified user. Each entry represents a dictionary item that the user has unlocked or acquired. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 10000 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Entries nextPageToken string Page token to retrieve the rest of the listing Implementation Example addEntriesByUserId Add entries by specifying a user ID Registers one or more entry model names to the specified user’s dictionary. Multiple entry model names can be specified at once in a batch operation. If an entry has already been registered, it is silently skipped without causing an error. The returned list contains only the entries that were newly added. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Added Entries Implementation Example getEntry Get an Entry Retrieves whether the currently logged-in user has collected a specific entry identified by entry model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item Entry Entry Implementation Example getEntryByUserId Get Entry by specifying a user ID Retrieves whether the specified user has collected a specific entry identified by entry model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Entry Entry Implementation Example getEntryWithSignature Get Entry with cryptographic signature Retrieves the entry for the currently logged-in user along with a cryptographic signature. The entry data is serialized to JSON and signed using the specified encryption key. The response includes the entry item, the serialized body, and the signature string, which can be used for tamper-proof verification on external systems. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Entry Entry body string Entry information for signature subject signature string signature Implementation Example getEntryWithSignatureByUserId Get Entry with cryptographic signature by specifying a user ID Retrieves the entry for the specified user along with a cryptographic signature. The entry data is serialized to JSON and signed using the specified encryption key. The response includes the entry item, the serialized body, and the signature string, which can be used for tamper-proof verification on external systems. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Entry Entry body string Entry information for signature subject signature string signature Implementation Example resetByUserId Reset entries Deletes all entries collected by the specified user, resetting their dictionary to an empty state. All collected entries are cleared at once. This action cannot be undone. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example verifyEntry Verify Entry Verifies whether the currently logged-in user has or has not collected a specific entry. The verify type specifies the condition: ‘have’ checks that the user has the entry, ‘havent’ checks that the user does not have it. If the verification fails, an error is returned. This is useful for implementing prerequisites (e.g., requiring a specific entry before allowing a quest). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). verifyType string (enum) enum {   “havent”,   “have” }  Type of verification Definition Description “havent” The specified entry must not be held “have” The specified entry must be held Result Type Description Implementation Example verifyEntryByUserId Verify Entry by specifying a user ID Verifies whether the specified user has or has not collected a specific entry. The verify type specifies the condition: ‘have’ checks that the user has the entry, ‘havent’ checks that the user does not have it. If the verification fails, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). verifyType string (enum) enum {   “havent”,   “have” }  Type of verification Definition Description “havent” The specified entry must not be held “have” The specified entry must be held timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example deleteEntries Delete entries Removes specific entries from the currently logged-in user’s dictionary by specifying a list of entry model names. Multiple entries can be deleted at once in a batch operation. The returned list contains the entries that were actually deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelNames List [] 0 ~ 100 items List of Entry Model names Result Type Description items List List of Deleted Entries Implementation Example deleteEntriesByUserId Delete entries by specifying a user ID Removes specific entries from the specified user’s dictionary by specifying a list of entry model names. Multiple entries can be deleted at once in a batch operation. The returned list contains the entries that were actually deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Deleted Entries Implementation Example describeLikes Get a list of Likes Retrieves a paginated list of entries that the currently logged-in user has marked as liked (favorited). Likes are separate from entry collection and represent user preferences for specific dictionary items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Likes nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeLikesByUserId Get a list of Likes by specifying a user ID Retrieves a paginated list of entries that the specified user has marked as liked (favorited). Likes are separate from entry collection and represent user preferences for specific dictionary items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Likes nextPageToken string Page token to retrieve the rest of the listing Implementation Example addLikes Add likes Marks one or more entries as liked by the currently logged-in user. Multiple entry model names can be specified at once in a batch operation. If an entry is already liked, it is silently skipped without causing an error. The returned list contains only the likes that were newly added. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelNames List [] 0 ~ 100 items List of Entry Model names Result Type Description items List List of Added Likes Implementation Example addLikesByUserId Add likes by specifying a user ID Marks one or more entries as liked by the specified user. Multiple entry model names can be specified at once in a batch operation. If an entry is already liked, it is silently skipped without causing an error. The returned list contains only the likes that were newly added. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Added Likes Implementation Example getLike Get Like Retrieves whether the currently logged-in user has liked a specific entry identified by entry model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item Like Like Entry Implementation Example getLikeByUserId Get Like by specifying a user ID Retrieves whether the specified user has liked a specific entry identified by entry model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Like Like Entry Implementation Example resetLikes Reset likes Deletes all likes for the currently logged-in user, resetting their favorites to an empty state. All liked entries are cleared at once. This action cannot be undone. Entry collection status is not affected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description Implementation Example resetLikesByUserId Reset likes by specifying a user ID Deletes all likes for the specified user, resetting their favorites to an empty state. All liked entries are cleared at once. This action cannot be undone. Entry collection status is not affected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example deleteLikes Delete likes Removes specific likes from the currently logged-in user by specifying a list of entry model names. Multiple likes can be removed at once in a batch operation. The returned list contains the likes that were actually deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token entryModelNames List [] 0 ~ 100 items List of Entry Model names Result Type Description items List List of Deleted Likes Implementation Example deleteLikesByUserId Delete likes by specifying a user ID Removes specific likes from the specified user by specifying a list of entry model names. Multiple likes can be removed at once in a batch operation. The returned list contains the likes that were actually deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Deleted Likes Implementation Example describeEntryModels Get a list of Entry Models Retrieves all currently active (published) Entry Models in the specified namespace. Entry Models define the types of dictionary items that users can collect. Only models that have been activated via the current master data are returned; editable master data is not included. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Entry Models Implementation Example getEntryModel Get Entry Model Retrieves the detailed information of a specific active Entry Model by name. The returned information includes the model’s name, metadata, and description. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). entryName string  ~ 128 chars Entry Model name Result Type Description item EntryModel Entry Model Implementation Example exportMaster Export Entry Model Master in a master data format that can be activated Exports the current Entry Model Master data in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentEntryMaster Entry Model master data that can be activated Implementation Example getCurrentEntryMaster Get currently active Entry Model master data Retrieves the master data of the Entry Models that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentEntryMaster Currently active Entry Model master data Implementation Example preUpdateCurrentEntryMaster Update currently active Entry Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentEntryMaster Update currently active Entry Model master data Updates and activates (publishes) the master data of the Entry Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentEntryMaster Updated master data of the currently active Entry Models Implementation Example updateCurrentEntryMasterFromGitHub Update currently active Entry Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentEntryMaster Updated master data of the currently active Entry Models Implementation Example describeEntryModelMasters Get a list of Entry Model Masters Retrieves a paginated list of editable Entry Model Masters with optional name prefix filtering. Entry Model Masters are the editable definitions for dictionary item types. Changes to masters do not take effect until the master data is activated via the CurrentEntryMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Entry Model name prefix 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 List of Entry Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createEntryModelMaster Create a new Entry Model Master Creates a new editable Entry Model Master definition with a name, description, and metadata. The created master defines a dictionary item type that users can collect. Changes do not take effect until the master data is activated via the CurrentEntryMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item EntryModelMaster Created Entry Model Master Implementation Example getEntryModelMaster Get Entry Model Master Retrieves the detailed information of a specific editable Entry Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). entryName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EntryModelMaster Entry Model Master Implementation Example updateEntryModelMaster Update Entry Model Master Updates the description and metadata of an existing Entry Model Master. The entry model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentEntryMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). entryName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item EntryModelMaster Entry Model Master updated Implementation Example deleteEntryModelMaster Delete Entry Model Master Deletes an editable Entry Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Existing user entries associated with the deleted model are not automatically removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). entryName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EntryModelMaster Entry Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Dictionary SDK for various programming languages\n","title":"GS2-Dictionary SDK API Reference","url":"/api_reference/dictionary/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how distributed transactions are executed when processing resource distribution. Supports auto-run, atomic commit, and async processing options. assumeUserId string ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN autoRunStampSheetNotification NotificationSetting  Push notification when transaction auto-execution is complete(Legacy specification) Configuration for sending push notifications via GS2-Gateway when a transaction completes auto-execution on the server side. This is the legacy specification; use autoRunTransactionNotification for the new specification. autoRunTransactionNotification NotificationSetting  Push notification when transaction auto-execution is complete Configuration for sending push notifications via GS2-Gateway when a distributed transaction completes auto-execution on the server side. Notifies the client of the transaction result so it can update the local state accordingly. logSetting LogSetting Log Output Setting Configuration for outputting log data of distributor operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for resource distribution, transaction execution, and transaction processing can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” StampSheetResult Transaction execution result (Legacy) Records the execution results of a transaction processed via server-side auto-execution. Contains the request payloads and response results for each phase: verify actions (precondition checks), consume actions (that deduct resources), and the acquire action (that grants resources). Also tracks HTTP status codes for error detection and retry logic. Details  stampSheetResultId string * ~ 1024 chars Transaction Result A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. verifyTaskRequests List 0 ~ 100 items List of verify action request payload taskRequests List 0 ~ 100 items List of Consume Action request payload sheetRequest AcquireAction  Acquire Action request payload verifyTaskResultCodes List [] 0 ~ 100 items Verify Action execution status code verifyTaskResults List [] 0 ~ 100 items Verify Action execution results taskResultCodes List [] 0 ~ 100 items Consume Action execution status code taskResults List [] 0 ~ 100 items Consume Action execution results sheetResultCode int 0 ~ 999 Acquire Action execution status code sheetResult string ~ 1048576 chars Acquire Action execution results nextTransactionId string 36 ~ 36 chars Transaction ID of the newly issued transaction by executing the transaction When the acquire action result contains a new transaction ID, it is extracted and stored here. This enables transaction chaining where one transaction’s completion triggers another transaction. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionResult Transaction execution result Records the execution results of a distributed transaction processed via server-side auto-execution. Contains structured results for each phase: verify actions (precondition checks), consume actions (resource deductions), and acquire actions (resource grants). Each action result includes the request, HTTP status code, and response payload. Errors are detected by checking status codes (non-2xx), and retries are triggered for conflict (409) or server errors (5xx). Details  transactionResultId string * ~ 1024 chars Transaction Result A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. verifyResults List 0 ~ 100 items List of verify action execution results consumeResults List 0 ~ 100 items List of Consume Action execution results acquireResults List 0 ~ 100 items List of acquire action execution results hasError bool false Whether an error occurred during transaction execution Set to true if any action (verify, consume, or acquire) returned a non-2xx status code. When true, the client should inspect individual action results to determine the failure cause. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision DistributorModel Distributor Model A Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages. Details  distributorModelId string * ~ 1024 chars Distributor Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Distributor Model name Distributor 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. BatchRequestPayload API Batch Request Represents a single API request within a batch execution. Multiple batch request payloads can be sent together to execute several GS2 API calls in a single round trip, reducing network overhead and latency. Details  requestId string  ~ 128 chars Request ID A client-assigned identifier for this request within the batch. Used to correlate each request with its corresponding result in the batch response. service string (enum) enum {   “account”,   “adReward”,   “auth”,   “buff”,   “chat”,   “datastore”,   “deploy”,   “dictionary”,   “distributor”,   “enchant”,   “enhance”,   “exchange”,   “experience”,   “formation”,   “friend”,   “gateway”,   “grade”,   “guard”,   “guild”,   “identifier”,   “idle”,   “inbox”,   “inventory”,   “jobQueue”,   “key”,   “limit”,   “lock”,   “log”,   “loginReward”,   “lottery”,   “matchmaking”,   “megaField”,   “mission”,   “money”,   “money2”,   “news”,   “quest”,   “ranking”,   “ranking2”,   “realtime”,   “schedule”,   “script”,   “seasonRating”,   “serialKey”,   “showcase”,   “skillTree”,   “stamina”,   “stateMachine”,   “version” }  Service The GS2 microservice name to call (e.g., “inventory”, “experience”, “money”). Determines which service endpoint receives this API request. Definition Description “account” GS2-Account “adReward” GS2-AdReward “auth” GS2-Auth “buff” GS2-Buff “chat” GS2-Chat “datastore” GS2-Datastore “deploy” GS2-Deploy “dictionary” GS2-Dictionary “distributor” GS2-Distributor “enchant” GS2-Enchant “enhance” GS2-Enhance “exchange” GS2-Exchange “experience” GS2-Experience “formation” GS2-Formation “friend” GS2-Friend “gateway” GS2-Gateway “grade” GS2-Grade “guard” GS2-Guard “guild” GS2-Guild “identifier” GS2-Identifier “idle” GS2-Idle “inbox” GS2-Inbox “inventory” GS2-Inventory “jobQueue” GS2-JobQueue “key” GS2-Key “limit” GS2-Limit “lock” GS2-Lock “log” GS2-Log “loginReward” GS2-LoginReward “lottery” GS2-Lottery “matchmaking” GS2-Matchmaking “megaField” GS2-MegaField “mission” GS2-Mission “money” GS2-Money “money2” GS2-Money2 “news” GS2-News “quest” GS2-Quest “ranking” GS2-Ranking “ranking2” GS2-Ranking2 “realtime” GS2-Realtime “schedule” GS2-Schedule “script” GS2-Script “seasonRating” GS2-SeasonRating “serialKey” GS2-SerialKey “showcase” GS2-Showcase “skillTree” GS2-SkillTree “stamina” GS2-Stamina “stateMachine” GS2-StateMachine “version” GS2-Version methodName string  ~ 128 chars Method Name The API method name to invoke on the target service (e.g., “describeNamespaces”, “getInventory”). Must match a valid API method for the specified service. parameter string  ~ 10240 chars Parameter The JSON-serialized request parameters for the API method. Must conform to the request schema of the specified service method. BatchResultPayload API Batch Result Represents the result of a single API request within a batch execution. Each result is correlated with its original request by the request ID and contains the HTTP status code and JSON response payload. Details  requestId string  ~ 128 chars Request ID The client-assigned identifier matching the corresponding batch request. Used to correlate this result with its original request. statusCode int  100 ~ 1000 Status Code The HTTP status code returned by the GS2 API for this batch request. 2xx indicates success, 4xx indicates a client error, and 5xx indicates a server error. resultPayload string  ~ 10240 chars Response The JSON response body returned by the GS2 API for this batch request. Contains the API method’s response data or error details. AcquireAction Acquire Action Represents a resource acquisition operation within a distributed transaction. Corresponds to an acquire action that grants resources (e.g., items, currency, experience) to the player. Contains the GS2 API action identifier and the JSON-serialized request parameters. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action Represents a resource consumption operation within a distributed transaction. Corresponds to a consume action that deducts resources (e.g., items, currency, stamina) from the player. Consume actions are executed before the acquire action to ensure the player meets the required cost. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Represents a precondition verification operation within a distributed transaction. Executed before consume and acquire actions to validate that conditions are met (e.g., checking inventory capacity, verifying quest completion status). If any verify action fails, the entire transaction is aborted. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireActionResult Acquire Action execution result Records the result of a single acquire action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API. Details  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 The HTTP status code returned by the GS2 API for this acquire action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. acquireResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the acquire action. Contains the details of the acquired resources and may include a chained transaction ID. ConsumeActionResult Consume Action execution result Records the result of a single consume action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API. Details  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 The HTTP status code returned by the GS2 API for this consume action. 2xx indicates success, 409 indicates a conflict requiring retry, and 5xx indicates a server error. consumeResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the consume action. Contains the details of the consumed resources. VerifyActionResult Verify Action execution result Records the result of a single verify action execution. Contains the action identifier, original request, HTTP status code indicating success or failure, and the JSON response payload from the GS2 API. Details  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 The HTTP status code returned by the GS2 API for this verify action. 2xx indicates the verification passed, and non-2xx indicates the precondition was not met. verifyResult string ~ 1048576 chars Result content The JSON response body returned by the GS2 API after executing the verify action. Contains the verification result details. Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value DistributeResource Distribute Resource Represents a single resource distribution operation consisting of an acquire action and its request parameters. Used to specify which GS2 API action to execute and with what parameters when distributing resources to a player. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action CurrentDistributorMaster Currently active Distributor Model master data This master data defines the Distributor Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Distributor Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data DistributorModelMaster Distributor Model Master Distributor Model Master is data used to edit and manage Distributor Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Distributor Model actually referenced by the game. Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages. Details  distributorModelId string * ~ 1024 chars Distributor Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how distributed transactions are executed when processing resource distribution. Supports auto-run, atomic commit, and async processing options. assumeUserId string ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN autoRunStampSheetNotification NotificationSetting  Push notification when transaction auto-execution is complete(Legacy specification) Configuration for sending push notifications via GS2-Gateway when a transaction completes auto-execution on the server side. This is the legacy specification; use autoRunTransactionNotification for the new specification. autoRunTransactionNotification NotificationSetting  Push notification when transaction auto-execution is complete Configuration for sending push notifications via GS2-Gateway when a distributed transaction completes auto-execution on the server side. Notifies the client of the transaction result so it can update the local state accordingly. logSetting LogSetting Log Output Setting Configuration for outputting log data of distributor operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for resource distribution, transaction execution, and transaction processing can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how distributed transactions are executed when processing resource distribution. Supports auto-run, atomic commit, and async processing options. assumeUserId string ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN autoRunStampSheetNotification NotificationSetting  Push notification when transaction auto-execution is complete(Legacy specification) Configuration for sending push notifications via GS2-Gateway when a transaction completes auto-execution on the server side. This is the legacy specification; use autoRunTransactionNotification for the new specification. autoRunTransactionNotification NotificationSetting  Push notification when transaction auto-execution is complete Configuration for sending push notifications via GS2-Gateway when a distributed transaction completes auto-execution on the server side. Notifies the client of the transaction result so it can update the local state accordingly. logSetting LogSetting Log Output Setting Configuration for outputting log data of distributor operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for resource distribution, transaction execution, and transaction processing can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example distribute Distribution of possessions Distributes resources to a user based on the action specified in the distribute resource. Supported services include Inventory, Stamina, Experience, Inbox, Money, and others. If the distribution causes the user’s holdings to exceed capacity, the overflow is automatically forwarded to the inbox namespace configured in the Distributor Model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID distributeResource DistributeResource  Resources to be added timeOffsetToken string ~ 1024 chars Time offset token Result Type Description distributeResource DistributeResource Processed DistributeResource inboxNamespaceId string GRN of the namespace of the gift box to be forwarded when the holdings are over capacity. result string Response content Implementation Example distributeWithoutOverflowProcess Distribute possessions (no bailout in case of overflow) Distributes resources to a user without overflow handling. Unlike the standard distribute operation, if the distribution causes the user’s holdings to exceed capacity, the excess is simply discarded and not forwarded to the inbox. This variant does not require a namespace specification. Details Request  userId string  ~ 128 chars User ID distributeResource DistributeResource  Resources to be added timeOffsetToken string ~ 1024 chars Time offset token Result Type Description distributeResource DistributeResource Processed DistributeResource result string Response content Implementation Example runVerifyTask Execute verify action of transaction Executes a single verify task within a transaction to check preconditions. The returned context stack reflects the verification result and is passed to subsequent tasks in the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyTask string  ~ 5242880 chars Verify Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runStampSheetExpress Execute transaction Executes all three phases of a transaction in sequence: verify actions, consume actions, and acquire action. This is a convenience API that combines RunVerifyTask, RunStampTask, and RunStampSheet into a single call. The results of all phases are returned together, including individual status codes and response content for each verify task, consume action, and the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description verifyTaskResultCodes List Verify Action execution status code verifyTaskResults List Verify Action execution results taskResultCodes List Consume Action execution status code taskResults List Consume Action execution results sheetResultCode int Acquire Action execution status code sheetResult string Acquire Action execution result response content Implementation Example runVerifyTaskWithoutNamespace Execute verify action of transaction without specifying the GS2-Distributor namespace Executes a verify task without specifying a GS2-Distributor namespace. By omitting the namespace specification, the following side effects occur: Execution logs are not recorded Resource overflow processing is not performed This is useful when a lightweight verify execution is needed without the overhead of namespace-level features. Details Request  verifyTask string  ~ 5242880 chars Verify Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runStampTaskWithoutNamespace Execute consume action of transaction without specifying the GS2-Distributor namespace Executes a consume action without specifying a GS2-Distributor namespace. By omitting the namespace specification, the following side effects occur: Execution logs are not recorded Resource overflow processing is not performed This is useful when a lightweight consume execution is needed without the overhead of namespace-level features. Details Request  stampTask string  ~ 5242880 chars Consume Action keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description contextStack string Context stack reflecting the task execution result statusCode int Status code result string Response content Implementation Example runStampSheetWithoutNamespace Execute acquire action of transaction without specifying the GS2-Distributor namespace Executes an acquire action without specifying a GS2-Distributor namespace. By omitting the namespace specification, the following side effects occur: Execution logs are not recorded Resource overflow processing is not performed (excess resources are discarded) This is useful when a lightweight acquire execution is needed without the overhead of namespace-level features. Details Request  stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description statusCode int Status code result string Response content Implementation Example runStampSheetExpressWithoutNamespace Execute transactions without specifying the GS2-Distributor namespace Executes all three phases of a transaction (verify, consume, acquire) in sequence without specifying a GS2-Distributor namespace. By omitting the namespace specification, the following side effects occur: Execution logs are not recorded Resource overflow processing is not performed (excess resources are discarded) This is useful when a lightweight full transaction execution is needed without the overhead of namespace-level features. Details Request  stampSheet string  ~ 5242880 chars Transaction keyId string  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description verifyTaskResultCodes List Verify Action execution status code verifyTaskResults List Verify Action execution results taskResultCodes List Consume Action execution status code taskResults List Consume Action execution results sheetResultCode int Acquire Action execution status code sheetResult string Acquire Action execution result response content Implementation Example setTransactionDefaultConfig Set the default value of Config to be specified for the Transaction Issuance API Sets default Config values that are automatically applied to subsequent transaction API calls. The default values are embedded in the returned ContextStack; by including this ContextStack in subsequent requests, the Config values are automatically applied. The default values are valid for 18 hours from the time they are set. After that, the values are ignored and must be set again. This is useful for setting commonly used Config values (such as slot names or rate model names) once without having to specify them in every transaction. Details Request  accessToken string  ~ 128 chars Access token config List  1 ~ 1000 items Configuration values applied to transaction placeholders Result Type Description newContextStack string Context stack for applying the default configuration Implementation Example setTransactionDefaultConfigByUserId Set the default value of Config to be specified for the Transaction Issuance API by specifying a user ID Sets default Config values that are automatically applied to subsequent transaction API calls for the specified user. The default values are embedded in the returned ContextStack; by including this ContextStack in subsequent requests, the Config values are automatically applied. The default values are valid for 18 hours from the time they are set. After that, the values are ignored and must be set again. This is useful for setting commonly used Config values (such as slot names or rate model names) once without having to specify them in every transaction. Details Request  userId string  ~ 128 chars User ID config List  1 ~ 1000 items Configuration values applied to transaction placeholders timeOffsetToken string ~ 1024 chars Time offset token Result Type Description newContextStack string Context stack for applying the default configuration Implementation Example freezeMasterData Freeze master data at the current time Freezes the master data at the current timestamp for the currently logged-in user. The freeze timestamp is recorded in the returned ContextStack; by including this ContextStack in subsequent requests, the master data as of the freeze time is used instead of the latest version. This ensures consistent master data during a series of related operations, preventing mid-operation changes from affecting the user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example freezeMasterDataByUserId Freeze master data at the current time by specifying a user ID Freezes the master data at the current timestamp for the specified user. The freeze timestamp is recorded in the returned ContextStack; by including this ContextStack in subsequent requests, the master data as of the freeze time is used instead of the latest version. This ensures consistent master data during a series of related operations, preventing mid-operation changes from affecting the user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example signFreezeMasterDataTimestamp Sign a timestamp for freezing master data Creates a cryptographic signature for a specified timestamp using the provided encryption key. The returned body and signature can be used with FreezeMasterDataBySignedTimestamp to freeze master data at the specified time. This allows server-side control over the freeze timestamp, preventing clients from specifying arbitrary timestamps. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timestamp long Current time Timestamp to freeze master data keyId string  ~ 1024 chars GS2-Key encryption key A unique resource name assigned to all information handled by GS2\" \u003e GRN used for signature calculation Result Type Description body string Body signature string Signature Implementation Example freezeMasterDataBySignedTimestamp Freeze master data at the specified signed timestamp Freezes the master data at a timestamp that was previously signed by SignFreezeMasterDataTimestamp. The signature is verified using the provided encryption key to ensure the timestamp has not been tampered with. The freeze timestamp is recorded in the returned ContextStack for use in subsequent requests. This is used when the server needs to control the exact freeze time to prevent client-side manipulation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token body string  ~ 1024 chars Body signature string  ~ 256 chars Signature keyId string  ~ 1024 chars GS2-Key encryption key A unique resource name assigned to all information handled by GS2\" \u003e GRN used for signature calculation Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example freezeMasterDataByTimestamp Freeze master data at the specified timestamp Freezes the master data at a directly specified timestamp without signature verification. The freeze timestamp is recorded in the returned ContextStack for use in subsequent requests. Unlike FreezeMasterDataBySignedTimestamp, the timestamp is not cryptographically verified, so this should only be used in trusted contexts. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token timestamp long  Timestamp to freeze master data Result Type Description newContextStack string Context recording the time at which master data is fixed Implementation Example batchExecuteApi Execute multiple APIs in bulk Executes multiple API calls in a single batch request, reducing the number of round-trips required. Up to 100 API calls can be included in a single batch. Each request in the batch is processed independently, and the results are returned in the same order as the requests. This is useful for reducing latency when multiple independent API calls need to be made. Details Request  requestPayloads List  1 ~ 100 items Batch request Result Type Description results List Batch result Implementation Example ifExpressionByUserId Validate the condition and switch the contents of the Consume Action Evaluates a verify action as a condition, and executes either the trueActions or falseActions list of consume actions based on the result. This enables conditional branching within a transaction, allowing different consume actions to be executed depending on the verification outcome. When multiplyValueSpecifyingQuantity is enabled, the values used for verification are also multiplied by the specified quantity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID condition VerifyAction  Condition trueActions List 0 ~ 10 items List of Consume Actions to be executed when the condition is true falseActions List 0 ~ 10 items List of Consume Actions to be executed when the condition is false multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TransactionResult Transaction execution result expressionResult bool? Result of condition evaluation Implementation Example andExpressionByUserId Perform multiple verification actions and determine if all are true Executes multiple verify actions and succeeds only if all of them evaluate to true (AND logic). If any verify action fails, the entire expression fails. This is useful for combining multiple preconditions that must all be satisfied before proceeding with a transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID actions List 0 ~ 10 items List of Verify Actions timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example orExpressionByUserId Perform multiple verification actions and determine if any are true Executes multiple verify actions and succeeds if at least one of them evaluates to true (OR logic). The expression fails only if all verify actions fail. This is useful for defining alternative conditions where satisfying any one of them is sufficient to proceed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID actions List 0 ~ 10 items List of Verify Actions timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example getStampSheetResult Get Transaction execution result Retrieves the execution results of a specific transaction for the currently logged-in user. The result contains the status codes and response content for each phase (verify, consume, acquire) of the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. Result Type Description item StampSheetResult Transaction execution result Implementation Example getStampSheetResultByUserId Get Transaction execution result by specifying a user ID Retrieves the execution results of a specific transaction for the specified user. The result contains the status codes and response content for each phase (verify, consume, acquire) of the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this transaction. Used to correlate the transaction with its execution results and any chained subsequent transactions. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item StampSheetResult Transaction execution result Implementation Example runTransaction Execute transaction Executes a transaction consisting of verify actions, consume actions, and acquire actions. The transaction is processed in order: verify -\u003e consume -\u003e acquire. The execution result including status codes and response content for each phase is recorded and can be retrieved later. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID transaction string  ~ 5242880 chars Transaction timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TransactionResult Transaction execution result Implementation Example getTransactionResult Get Transaction execution result Retrieves the execution results of a specific transaction for the currently logged-in user. The result contains the status codes and response content for each phase (verify, consume, acquire) of the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. Result Type Description item TransactionResult Transaction execution result Implementation Example getTransactionResultByUserId Get Transaction execution result by specifying a user ID Retrieves the execution results of a specific transaction for the specified user. The result contains the status codes and response content for each phase (verify, consume, acquire) of the transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID transactionId string  36 ~ 36 chars Transaction ID A UUID that uniquely identifies this distributed transaction. Used to look up the execution results and correlate with the originating API request. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item TransactionResult Transaction execution result Implementation Example describeDistributorModels Get a list of Distributor Models Retrieves all currently active (published) Distributor Models in the specified namespace. Distributor Models define the resource distribution rules, including the inbox namespace for overflow handling and the whitelist of target service actions. Only models that have been activated via the current master data are returned; editable master data is not included. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Distributor Models Implementation Example getDistributorModel Get Distributor Model Retrieves the detailed information of a specific active Distributor Model by name. The returned information includes the model’s name, metadata, inbox namespace for overflow handling, and whitelist of target service actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item DistributorModel Distributor Model Implementation Example exportMaster Export Distributor Model Master in a master data format that can be activated Exports the current Distributor Model Master data in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentDistributorMaster Distributor Model master data that can be activated Implementation Example getCurrentDistributorMaster Get currently active Distributor Model master data Retrieves the master data of the Distributor Models that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentDistributorMaster Currently active Distributor Model master data Implementation Example preUpdateCurrentDistributorMaster Update currently active Distributor Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentDistributorMaster Update currently active Distributor Model master data Updates and activates (publishes) the master data of the Distributor Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentDistributorMaster Updated master data of the currently active Distributor Models Implementation Example updateCurrentDistributorMasterFromGitHub Update currently active Distributor Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentDistributorMaster Updated master data of the currently active Distributor Models Implementation Example describeDistributorModelMasters Get a list of Distributor Model Masters Retrieves a paginated list of editable Distributor Model Masters with optional name prefix filtering. Distributor Model Masters are the editable definitions for resource distribution rules. Changes to masters do not take effect until the master data is activated via the CurrentDistributorMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Distributor Model Master name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Distributor Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createDistributorModelMaster Create a new Distributor Model Master Creates a new editable Distributor Model Master definition with a name, description, metadata, inbox namespace for overflow handling, and whitelist of target service actions. The inbox namespace specifies where resources are forwarded when the user’s holdings exceed capacity. The whitelist restricts which service actions are allowed to be distributed through this model. Changes do not take effect until the master data is activated via the CurrentDistributorMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. Result Type Description item DistributorModelMaster Created Distributor Model Master Implementation Example getDistributorModelMaster Get Distributor Model Master Retrieves the detailed information of a specific editable Distributor Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item DistributorModelMaster Distributor Model Master Implementation Example updateDistributorModelMaster Update Distributor Model Master Updates the description, metadata, inbox namespace, and whitelist of an existing Distributor Model Master. The distributor model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentDistributorMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model. Result Type Description item DistributorModelMaster Distributor Model Master updated Implementation Example deleteDistributorModelMaster Delete Distributor Model Master Deletes an editable Distributor Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). distributorName string  ~ 128 chars Distributor Model name Distributor Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item DistributorModelMaster Distributor Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Distributor SDK for various programming languages\n","title":"GS2-Distributor SDK API Reference","url":"/api_reference/distributor/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing enchant parameter operations. logSetting LogSetting Log Output Setting Configuration for outputting log data of enchant operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for balance parameter and rarity parameter operations can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” BalanceParameterStatus Balance Parameter Status Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Balance Parameter Model and contains the concrete values assigned to each parameter slot after the drawing process. Details  balanceParameterStatusId string * ~ 1024 chars Balance Parameter A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List  1 ~ 10 items List of balance parameter values The concrete values assigned to each parameter slot after the drawing process. Each entry corresponds to a parameter slot defined in the model and contains the actual numeric value allocated. The sum of all values equals the total value specified in the model. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RarityParameterStatus Rarity Parameter Status Represents the actual parameter values drawn for a specific resource owned by a user. Each status is associated with a Rarity Parameter Model and contains the concrete values selected through weighted lottery for each granted parameter slot. Details  rarityParameterStatusId string * ~ 1024 chars Rarity Parameter Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List 0 ~ 10 items List of rarity parameter values The concrete parameter values selected through weighted lottery for each granted slot. The number of entries is determined by the parameter count draw, and each entry’s value is selected from the value model pool. May contain fewer entries than the maximum parameter count. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BalanceParameterModel Balance Parameter Model Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters. Details  balanceParameterModelId string * ~ 1024 chars Balance Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. RarityParameterModel Rarity Parameter Model Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions. Details  rarityParameterModelId string * ~ 1024 chars Rarity Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. BalanceParameterValueModel Balance Parameter Value Model Defines a single parameter slot available within a balance parameter. Each entry specifies a named slot (e.g., ATK, DEF, SPD) that receives a portion of the total value during the drawing process. Details  name string  ~ 64 chars Name The identifier for this parameter slot (e.g., ATK, DEF, SPD). Must be unique within the balance parameter model. Used as the key when storing and retrieving drawn parameter values. metadata string ~ 512 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. RarityParameterCountModel Rarity Parameter Count Model Defines a single entry in the weighted lottery for determining how many parameter slots are granted to a resource. Each entry pairs a parameter count with a draw weight, allowing fine-grained control over the probability distribution of parameter quantities. Details  count int  0 ~ 10 Count The number of parameter slots to grant when this entry is drawn. For example, a count of 3 means the resource will receive 3 parameter values selected from the value model pool. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when determining the parameter count. Higher values increase the probability of this count being selected. The actual probability is this weight divided by the sum of all weights in the count model list. RarityParameterValueModel Rarity Parameter Value Model Defines a single entry in the weighted lottery pool for rarity parameter values. Each entry specifies a parameter name, game-defined resource details, and a draw weight that determines its selection probability relative to other entries in the pool. Details  name string  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. metadata string ~ 512 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. resourceName string  ~ 64 chars Parameter Resource Name for Game (Not used for GS2) A game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. resourceValue long  0 ~ 9223372036854775805 Parameter Resource Value for Game (Not used for GS2) A game-defined numeric value for this parameter (e.g., 50 for +50 attack power). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when selecting parameter values. Higher values increase the probability of this entry being selected. The actual probability is this weight divided by the sum of all weights in the pool. BalanceParameterValue Balance Parameter Value Represents the actual value assigned to a single parameter slot within a balance parameter status. Contains the slot name and its concrete numeric value after the drawing process. Details  name string  ~ 64 chars Name The name of the parameter slot (e.g., ATK, DEF, SPD). Corresponds to a parameter slot defined in the Balance Parameter Value Model. value long  0 ~ 9223372036854775805 Value The numeric value assigned to this parameter slot. Determined by the initial value strategy (average or lottery) when the balance parameter is first drawn. The sum of all slot values equals the total value defined in the model. RarityParameterValue Rarity Parameter Value Represents the actual value assigned to a single parameter slot within a rarity parameter status. Contains the slot name and the resource details (name and value) selected through weighted lottery from the value model pool. Details  name string  ~ 64 chars Name The name of the parameter value selected from the value model pool. Corresponds to the name defined in the Rarity Parameter Value Model entry that was drawn. resourceName string  ~ 64 chars Resource Name The game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). Copied from the drawn Rarity Parameter Value Model entry for use in game logic. resourceValue long  0 ~ 9223372036854775805 Resource Value The numeric value of the resource associated with this parameter. Copied from the drawn Rarity Parameter Value Model entry. Used by game logic to apply the parameter’s effect (e.g., +50 attack power). VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value CurrentParameterMaster Currently active Parameter Model master data This master data defines the Parameter Models currently active within the namespace. GS2 uses JSON format files for master data management. By uploading the file, the settings can actually be reflected on the server. To create JSON files, we provide a master data editor within the management console. Additionally, you can utilize the service by creating tools more suited to game operations and exporting JSON files in the appropriate format. Note Please refer to GS2-Enchant Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data BalanceParameterModelMaster Balance Parameter Model Master Editable version of the Balance Parameter Model used for management console operations. Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters. Details  balanceParameterModelId string * ~ 1024 chars Balance Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RarityParameterModelMaster Rarity Parameter Model Master Editable version of the Rarity Parameter Model used for management console operations. Defines the drawing conditions for rarity parameters using a weighted lottery system to determine both the number of parameters granted and the specific values assigned. Details  rarityParameterModelId string * ~ 1024 chars Rarity Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing enchant parameter operations. logSetting LogSetting Log Output Setting Configuration for outputting log data of enchant operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for balance parameter and rarity parameter operations can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing enchant parameter operations. logSetting LogSetting Log Output Setting Configuration for outputting log data of enchant operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for balance parameter and rarity parameter operations can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeBalanceParameterStatuses Get a list of Balance Parameter Statuses Retrieves a paginated list of balance parameter statuses for the currently logged-in user. Results can be optionally filtered by parameter name to retrieve statuses for a specific parameter model. Each status represents the current parameter values assigned to a specific property (e.g., an item). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token parameterName string ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. 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 List of Balance Parameter Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeBalanceParameterStatusesByUserId Get a list of Balance Parameter Statuses by specifying a user ID Retrieves a paginated list of balance parameter statuses for the specified user. Results can be optionally filtered by parameter name to retrieve statuses for a specific parameter model. Each status represents the current parameter values assigned to a specific property (e.g., an item). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Balance Parameter Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example getBalanceParameterStatus Get Balance Parameter Status Retrieves the current balance parameter values for a specific property of the currently logged-in user. The status contains the parameter values that were assigned when the parameters were first drawn or last re-drawn, where the sum of all values equals the model’s total value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. Result Type Description item BalanceParameterStatus Balance Parameter Status Implementation Example getBalanceParameterStatusByUserId Get Balance Parameter Status by specifying a user ID Retrieves the current balance parameter values for a specific property of the specified user. The status contains the parameter values that were assigned when the parameters were first drawn or last re-drawn, where the sum of all values equals the model’s total value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BalanceParameterStatus Balance Parameter Status Implementation Example deleteBalanceParameterStatusByUserId Delete Balance Parameter Status Deletes the balance parameter status for a specific property of the specified user. Once deleted, the parameter values are permanently removed and cannot be recovered. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BalanceParameterStatus Balance Parameter Status deleted Implementation Example reDrawBalanceParameterStatusByUserId Re-draw balance parameter by specifying a user ID Re-draws the balance parameter values for a specific property, redistributing the total value among the parameters. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). The total value constraint is maintained: the sum of all parameter values (including fixed ones) always equals the model’s total value. Both the updated and previous parameter states are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. fixedParameterNames List [] 0 ~ 10 items List of Parameter index not to re-draw timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BalanceParameterStatus Balance Parameter Status updated old BalanceParameterStatus Balance Parameter Status before update Implementation Example setBalanceParameterStatusByUserId Set any value to Balance Parameter Status by specifying a user ID Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned. Both the updated and previous parameter states are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List  1 ~ 10 items List of balance parameter values The concrete values assigned to each parameter slot after the drawing process. Each entry corresponds to a parameter slot defined in the model and contains the actual numeric value allocated. The sum of all values equals the total value specified in the model. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BalanceParameterStatus Balance Parameter Status updated old BalanceParameterStatus Balance Parameter Status before update Implementation Example describeRarityParameterStatuses Get a list of Rarity Parameter Statuses Retrieves a paginated list of rarity parameter statuses for the currently logged-in user. Results can be optionally filtered by parameter name to retrieve statuses for a specific parameter model. Each status represents the current set of rarity-based parameter values assigned to a specific property (e.g., an item). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token parameterName string ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. 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 List of Rarity Parameter Models nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeRarityParameterStatusesByUserId Get a list of Rarity Parameter Statuses by specifying a user ID Retrieves a paginated list of rarity parameter statuses for the specified user. Results can be optionally filtered by parameter name to retrieve statuses for a specific parameter model. Each status represents the current set of rarity-based parameter values assigned to a specific property (e.g., an item). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Rarity Parameter Models nextPageToken string Page token to retrieve the rest of the listing Implementation Example getRarityParameterStatus Get Rarity Parameter Status Retrieves the current rarity parameter values for a specific property of the currently logged-in user. The status contains the parameter values that were randomly drawn based on the rarity weights defined in the model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. Result Type Description item RarityParameterStatus Rarity Parameter Status Implementation Example getRarityParameterStatusByUserId Get Rarity Parameter Status by specifying a user ID Retrieves the current rarity parameter values for a specific property of the specified user. The status contains the parameter values that were randomly drawn based on the rarity weights defined in the model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status Implementation Example deleteRarityParameterStatusByUserId Delete Rarity Parameter Status Deletes the rarity parameter status for a specific property of the specified user. Once deleted, the parameter values are permanently removed and cannot be recovered. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status deleted Implementation Example reDrawRarityParameterStatusByUserId Re-draw Rarity Parameter Status by specifying a user ID Re-draws the rarity parameter values for a specific property, randomly assigning new values based on the rarity weights. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). Fixed parameters retain their current values while unfixed parameters are re-drawn. Both the updated and previous parameter states are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. fixedParameterNames List 0 ~ 10 items List of Parameter index not to re-draw timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status updated old RarityParameterStatus Rarity Parameter Status before update Implementation Example addRarityParameterStatusByUserId Add Rarity Parameter to status by specifying a user ID Adds new parameter slots to an existing rarity parameter status by randomly drawing values based on the rarity weights. The count specifies how many parameter slots to add (1 to 10), up to the model’s maximum parameter count. Both the updated and previous parameter states are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. count int 1 1 ~ 10 Number of parameters to add timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status updated old RarityParameterStatus Rarity Parameter Status before update Implementation Example verifyRarityParameterStatus Verify rarity parameter Verifies that a rarity parameter status meets the specified condition. Three verification types are supported: ‘have’: Verifies that the specified parameter value exists in the status ‘havent’: Verifies that the specified parameter value does not exist in the status ‘count’: Verifies that the number of parameters matches the specified count This can be used as a precondition check before executing other actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. verifyType string (enum) enum {   “havent”,   “have”,   “count” }  Type of verification Definition Description “havent” The specified parameter must not be held “have” The specified parameter must be held “count” The number of parameters held must be the specified number parameterValueName string {verifyType} in [“havent”, “have”]  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. * Required if verifyType is “havent”,“have” parameterCount int {verifyType} in [“count”]  0 ~ 10 Number of parameters to verify multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item RarityParameterStatus Rarity Parameter Status Implementation Example verifyRarityParameterStatusByUserId Verify rarity parameter by specifying a user ID Verifies that a rarity parameter status of the specified user meets the specified condition. Three verification types are supported: ‘have’: Verifies that the specified parameter value exists in the status ‘havent’: Verifies that the specified parameter value does not exist in the status ‘count’: Verifies that the number of parameters matches the specified count This can be used as a precondition check before executing other actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. verifyType string (enum) enum {   “havent”,   “have”,   “count” }  Type of verification Definition Description “havent” The specified parameter must not be held “have” The specified parameter must be held “count” The number of parameters held must be the specified number parameterValueName string {verifyType} in [“havent”, “have”]  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. * Required if verifyType is “havent”,“have” parameterCount int {verifyType} in [“count”]  0 ~ 10 Number of parameters to verify multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status Implementation Example setRarityParameterStatusByUserId Set any value to rarity parameter by specifying a user ID Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned regardless of rarity weights. Both the updated and previous parameter states are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List 0 ~ 10 items List of rarity parameter values The concrete parameter values selected through weighted lottery for each granted slot. The number of entries is determined by the parameter count draw, and each entry’s value is selected from the value model pool. May contain fewer entries than the maximum parameter count. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RarityParameterStatus Rarity Parameter Status updated old RarityParameterStatus Rarity Parameter Status before update Implementation Example describeBalanceParameterModels Get a list of Balance Parameter Models Retrieves all currently active (published) Balance Parameter Models in the specified namespace. Balance Parameter Models define parameter sets where the total value is distributed among multiple parameters, ensuring the sum always equals a fixed total. Only models that have been activated via the current master data are returned; editable master data is not included. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Balance Parameter Model Implementation Example getBalanceParameterModel Get Balance Parameter Model Retrieves the detailed information of a specific active Balance Parameter Model by name. The returned information includes the model’s name, metadata, total value, initial value strategy, and parameter definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item BalanceParameterModel Balance Parameter Model Implementation Example describeRarityParameterModels Get a list of Rarity Parameter Models Retrieves all currently active (published) Rarity Parameter Models in the specified namespace. Rarity Parameter Models define parameter sets where each parameter slot is filled by a randomly drawn value with rarity-based probabilities. Only models that have been activated via the current master data are returned; editable master data is not included. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Rarity Parameter Models Implementation Example getRarityParameterModel Get Rarity Parameter Model Retrieves the detailed information of a specific active Rarity Parameter Model by name. The returned information includes the model’s name, metadata, maximum parameter count, parameter count distribution, and parameter value definitions with their rarity weights. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item RarityParameterModel Rarity Parameter Model Implementation Example exportMaster Export Parameter Model Master in a master data format that can be activated Exports the current Parameter Model Master data (both Balance Parameter Models and Rarity Parameter Models) in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentParameterMaster Parameter Model master data that can be activated Implementation Example getCurrentParameterMaster Get currently active Parameter Model master data Retrieves the master data of the Parameter Models (both Balance and Rarity) that are currently active (published) in the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentParameterMaster Currently active Parameter Model master data Implementation Example preUpdateCurrentParameterMaster Update currently active Parameter Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentParameterMaster Update currently active Parameter Model master data Updates and activates (publishes) the master data of the Parameter Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentParameterMaster Updated master data of the currently active Parameter Models Implementation Example updateCurrentParameterMasterFromGitHub Updates currently active Parameter Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentParameterMaster Updated master data of the currently active Parameter Models Implementation Example describeBalanceParameterModelMasters Get a list of Balance Parameter Model Master Retrieves a paginated list of editable Balance Parameter Model Masters with optional name prefix filtering. Balance Parameter Model Masters are the editable definitions for balance parameter sets. Changes to masters do not take effect until the master data is activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Balance Parameter Model name prefix 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 List of Balance Parameter Model Master Data nextPageToken string Page token to retrieve the rest of the listing Implementation Example createBalanceParameterModelMaster Create a new Balance Parameter Model Master Creates a new editable Balance Parameter Model Master definition. The total value specifies the sum that is distributed among the parameters, and the initial value strategy determines how values are initially assigned. The parameters define the individual parameter slots with their value ranges. Changes do not take effect until the master data is activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. Result Type Description item BalanceParameterModelMaster Balance Parameter Model Master created Implementation Example getBalanceParameterModelMaster Get Balance Parameter Model Master Data Retrieves the detailed information of a specific editable Balance Parameter Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item BalanceParameterModelMaster Balance Parameter Model Master Implementation Example updateBalanceParameterModelMaster Update Balance Parameter Model Master Data Updates the description, metadata, total value, initial value strategy, and parameters of an existing Balance Parameter Model Master. The parameter model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. Result Type Description item BalanceParameterModelMaster Balance Parameter Model Master Data updated Implementation Example deleteBalanceParameterModelMaster Delete Balance Parameter Model Master Data Deletes an editable Balance Parameter Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Existing user parameter statuses associated with the deleted model are not automatically removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item BalanceParameterModelMaster Balance Parameter Model Master deleted Implementation Example describeRarityParameterModelMasters Get a list of Rarity Parameter Model Masters Retrieves a paginated list of editable Rarity Parameter Model Masters. Rarity Parameter Model Masters are the editable definitions for rarity-based parameter sets. Changes to masters do not take effect until the master data is activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Rarity Parameter Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRarityParameterModelMaster Create a new Rarity Parameter Model Master Creates a new editable Rarity Parameter Model Master definition. The maximum parameter count specifies the upper limit of parameter slots, and parameter counts define the probability distribution for how many slots are filled. The parameters define the possible values with their rarity-based draw weights. Changes do not take effect until the master data is activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. Result Type Description item RarityParameterModelMaster Rarity Parameter Model Master created Implementation Example getRarityParameterModelMaster Get Rarity Parameter Model Master Retrieves the detailed information of a specific editable Rarity Parameter Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item RarityParameterModelMaster Rarity Parameter Model Master Implementation Example updateRarityParameterModelMaster Update Rarity Parameter Model Master Updates the description, metadata, maximum parameter count, parameter counts, and parameters of an existing Rarity Parameter Model Master. The parameter model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentParameterMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. Result Type Description item RarityParameterModelMaster Rarity Parameter Model Master updated Implementation Example deleteRarityParameterModelMaster Delete Rarity Parameter Model Master Deletes an editable Rarity Parameter Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Existing user parameter statuses associated with the deleted model are not automatically removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item RarityParameterModelMaster Rarity Parameter Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Enchant SDK for various programming languages\n","title":"GS2-Enchant SDK API Reference","url":"/api_reference/enchant/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing enhancement operations. Supports auto-run, atomic commit, and async processing options. enhanceScript ScriptSetting Script setting to be executed at the time of enhancement Script Trigger Reference - enhance logSetting LogSetting Log Output Setting Configuration for outputting log data of enhancement operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for enhancement and limit break operations can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Progress Enhance Progress It is created at the beginning of the enhance and deleted at the end. When you exit the application in the middle of an enhance, this data will remain. It is possible to resume the game from the ongoing enhance information maintained by the entity. Details  progressId string * ~ 1024 chars Progress A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. name string  UUID ~ 36 chars Progress ID Maintains a unique name for each enhance progress. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each enhance progress. propertyId string  ~ 1024 chars Property ID to be enhanced The property ID of the GS2-Inventory item being enhanced. Identifies the specific item instance that will receive experience points upon completion of the enhancement. experienceValue long  0 ~ 9223372036854775805 Experience value obtainable The base experience value calculated from the consumed materials. This value is determined by summing the experience values defined in each material’s metadata, multiplied by the material quantity. rate float  0 ~ 100.0 Experience value scale factor The bonus multiplier applied to the base experience value. Determined by weighted lottery from the Enhancement Rate Model’s bonus rates. A value of 1.0 means no bonus, while values greater than 1.0 represent a “great success” bonus (e.g., 1.5 for 150% experience). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RateModel Enhancement Rate Model The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity. Details  rateModelId string * ~ 1024 chars Enhancement Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model. acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy. acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ] Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix. bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. UnleashRateModel Unleash Rate Model Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step. Details  unleashRateModelId string * ~ 1024 chars Unleash Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model. gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on. UnleashRateEntryModel Unleash Rate Entry Model Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade. Details  gradeValue long  1 ~ 1000 Target grade The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed. needCount int  1 ~ 1000 How many items of the same type to consume The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed. BonusRate Experience Gain Bonus Defines a single entry in the weighted lottery for determining the experience bonus multiplier during enhancement. By configuring multiple entries with different rates and weights, you can implement “great success” or “super success” mechanics with controlled probabilities. Details  rate float 1.0 0 ~ 10000 Experience bonus multiplier (1.0 = no bonus) The multiplier applied to the base experience value when this entry is drawn. A value of 1.0 means normal enhancement with no bonus, 1.5 means 150% experience (great success), 2.0 means 200% experience (super success), and so on. weight int 1 0 ~ 2147483645 Lottery weight The relative weight used in the weighted lottery when selecting the bonus rate. Higher values increase the probability of this bonus rate being selected. The actual probability is this weight divided by the sum of all weights in the bonus rate list. Material Enhance Material Represents a material item to be consumed during an enhancement operation. Each material references a specific GS2-Inventory item set and specifies the quantity to consume. The experience value provided by the material is determined from the item model’s metadata. Details  materialItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of Item Set that will be used as materials for enhancement References the specific GS2-Inventory item set to consume as enhancement material. The item must belong to the material inventory model specified in the Enhancement Rate Model. count int 1 0 ~ 2147483645 Number of consumption The quantity of this material item to consume. The total experience gained from this material is calculated by multiplying the per-item experience value (from the item model metadata) by this count. Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentRateMaster Currently active Rate Model master data This master data defines the Rate Models currently active within the namespace. GS2 uses JSON format files for master data management. By uploading the file, the settings can actually be reflected on the server. To create JSON files, we provide a master data editor within the management console. Additionally, you can utilize the service by creating tools more suited to game operations and exporting JSON files in the appropriate format. Note Please refer to GS2-Enhance Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data RateModelMaster Enhancement Rate Model Master Enhancement Rate Model Master is data used to edit and manage Enhancement Rate Models within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Enhancement Rate Model actually referenced by the game. The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity. Details  rateModelId string * ~ 1024 chars Enhancement Rate Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model. acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy. acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, if you have metadata like { “aaa”: { “bbb”: { “experienceValue”: 100 } } }, specify [ “aaa”, “bbb”, “experienceValue” ]. Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix. bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision UnleashRateModelMaster Unleash Rate Model Master Editable version of the Unleash Rate Model used for management console operations. Defines the conditions for limit breaking (unleashing) items by associating a GS2-Inventory item with a GS2-Grade grade model. Each grade level can require consuming a different number of duplicate items. Details  unleashRateModelId string * ~ 1024 chars Unleash Rate Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata Any value can be set for metadata. It does not affect the operation of GS2 in any way, and should be used as a storage location for values used in the game. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model. gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing enhancement operations. Supports auto-run, atomic commit, and async processing options. enhanceScript ScriptSetting Script setting to be executed at the time of enhancement Script Trigger Reference - enhance logSetting LogSetting Log Output Setting Configuration for outputting log data of enhancement operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for enhancement and limit break operations can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing enhancement operations. Supports auto-run, atomic commit, and async processing options. enhanceScript ScriptSetting Script setting to be executed at the time of enhancement Script Trigger Reference - enhance logSetting LogSetting Log Output Setting Configuration for outputting log data of enhancement operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for enhancement and limit break operations can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example directEnhance Perform enhancements Consumes the specified materials to grant experience to the target item set based on the Enhanced Rate Model. The experience gained is calculated from the materials according to the experience hierarchy defined in the rate model, and a bonus rate is drawn from the configured bonus rate probability table. The result includes the acquired experience amount and the bonus rate applied. A transaction (transaction) is issued to execute the material consumption and experience acquisition. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List  1 ~ 10 items List of Material config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item RateModel Enhanced Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to perform the enhancement process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example directEnhanceByUserId Perform enhancement by specifying a user ID Consumes the specified materials to grant experience to the target item set based on the Enhanced Rate Model. The experience gained is calculated from the materials according to the experience hierarchy defined in the rate model, and a bonus rate is drawn from the configured bonus rate probability table. The result includes the acquired experience amount and the bonus rate applied. A transaction (transaction) is issued to execute the material consumption and experience acquisition. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List  1 ~ 10 items List of Material config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RateModel Enhanced Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to perform the enhancement process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example unleash Perform unleash Used for enhancement processing to raise the grade of the resource managed by GS2-Grade. In particular, it is used for the type of unleash that raises the level cap by consuming the same type of item as a material. Instead of consuming the specified material, the grade of the resource to be unleashed can be increased by 1. Even if the material resource has a resource such as experience value, the resource will not be inherited. If inheritance is required, the resource must be converted to a resource for inheritance in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the Item Set subject to limit break materials List  1 ~ 1000 items List of materials that break the limit config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item UnleashRateModel Unleash Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to perform the enhancement process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example unleashByUserId Perform unleash by specifying a user ID Used for enhancement processing to raise the grade of the resource managed by GS2-Grade. In particular, it is used for the type of unleash that raises the level cap by consuming the same type of item as a material. Instead of consuming the specified material, the grade of the resource to be unleashed can be increased by 1. Even if the material resource has a resource such as experience value, the resource will not be inherited. If inheritance is required, the resource must be converted to a resource for inheritance in advance. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the Item Set subject to limit break materials List  1 ~ 1000 items List of materials that break the limit config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item UnleashRateModel Unleash Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to perform the enhancement process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example createProgressByUserId Start enhancement by specifying a user ID Creates a progress record for a 2-phase enhancement flow. Validates the target item set and materials against the rate model, calculates the experience to be gained from the materials, and draws a bonus rate from the probability table. The calculated experience and bonus rate are stored in the progress record for later use when the enhancement is completed via the End API. If force is true, any existing progress for the user will be discarded and replaced. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List 0 ~ 10 items List of materials force bool false If there is an enhancement that has already been started, it can be discarded and started, or timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Progress information for the enhancement currently in the running Implementation Example getProgress Retrieve running enhancements Retrieves the progress information of the enhancement currently in progress for the authenticated user. The progress record contains the rate name, target item set, materials, calculated experience, and drawn bonus rate that were determined at the start of the enhancement. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Progress Progress information for the enhancement currently in the running Implementation Example getProgressByUserId Get running enhancements by specifying a user ID Retrieves the progress information of the enhancement currently in progress for the specified user. The progress record contains the rate name, target item set, materials, calculated experience, and drawn bonus rate that were determined at the start of the enhancement. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Progress information for the enhancement currently in the running Implementation Example start Start enhancement Initiates a 2-phase enhancement process for the authenticated user. Creates a progress record by validating the target and materials against the rate model, calculating experience, and drawing a bonus rate. A transaction (transaction) is issued to consume the specified materials. If force is true, any existing progress for the user will be discarded and replaced. After materials are consumed, call the End API to complete the enhancement and grant the calculated experience. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List 0 ~ 10 items List of materials accessToken string  ~ 128 chars Access token force bool false If there is an enhancement that has already been started, it can be discarded and started, or config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the enhancement initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example startByUserId Start enhancement by specifying a user ID Initiates a 2-phase enhancement process for the specified user. Creates a progress record by validating the target and materials against the rate model, calculating experience, and drawing a bonus rate. A transaction (transaction) is issued to consume the specified materials. If force is true, any existing progress for the user will be discarded and replaced. After materials are consumed, call the End API to complete the enhancement and grant the calculated experience. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List 0 ~ 10 items List of materials userId string  ~ 128 chars User ID force bool false If there is an enhancement that has already been started, it can be discarded and started, or config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the enhancement initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example end Complete enhancement Completes the 2-phase enhancement process for the authenticated user. Retrieves the progress record created during the Start phase, which contains the pre-calculated experience and bonus rate. A transaction (transaction) is issued to grant the calculated experience (with bonus rate applied) to the target item. The progress record is deleted after the enhancement is completed. The response includes the acquired experience amount and the bonus rate that was applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Progress progress information for enhancement transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example endByUserId Complete enhancement by specifying a user ID Completes the 2-phase enhancement process for the specified user. Retrieves the progress record created during the Start phase, which contains the pre-calculated experience and bonus rate. A transaction (transaction) is issued to grant the calculated experience (with bonus rate applied) to the target item. The progress record is deleted after the enhancement is completed. The response includes the acquired experience amount and the bonus rate that was applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress progress information for enhancement transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result acquireExperience long Amount of experience gained bonusRate float Experience bonus multiplier (1.0 = no bonus) Implementation Example deleteProgress Delete running enhancement Deletes the progress record of the enhancement currently in progress for the authenticated user. This cancels the ongoing 2-phase enhancement, discarding the pre-calculated experience and bonus rate. Materials that were already consumed during the Start phase are not automatically refunded. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Progress Progress information for enhancement Implementation Example deleteProgressByUserId Delete running enhancement by specifying a user ID Deletes the progress record of the enhancement currently in progress for the specified user. This cancels the ongoing 2-phase enhancement, discarding the pre-calculated experience and bonus rate. Materials that were already consumed during the Start phase are not automatically refunded. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Progress information for enhancement Implementation Example describeRateModels Get a list of Enhanced Rate Models Retrieves the list of currently active (published) Enhanced Rate Models in the specified namespace. Each Rate Model defines the enhancement configuration including the target inventory model, material inventory model, experience hierarchy, experience suffix, and bonus rates. Only models that have been activated via the CurrentRateMaster are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Enhanced Rate Models Implementation Example getRateModel Get Enhanced Rate Model Retrieves the detailed information of a specific currently active Enhanced Rate Model by name. The returned model includes the target inventory model ID, material inventory model ID, acquire experience suffix, acquire experience hierarchy, experience model ID, and bonus rate definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModel Enhanced Rate Model Implementation Example describeUnleashRateModels Get a list of Unleash Rate Models Retrieves the list of currently active (published) Unleash Rate Models in the specified namespace. Each Unleash Rate Model defines the limit break configuration including the target inventory model, grade model, and grade entries that specify materials required for each grade level. Only models that have been activated via the CurrentRateMaster are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Unleash Rate Model Implementation Example getUnleashRateModel Get Unleash Rate Model Retrieves the detailed information of a specific currently active Unleash Rate Model by name. The returned model includes the target inventory model ID, grade model ID, and grade entries that define the material requirements for each grade level of the limit break. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item UnleashRateModel Unleash Rate Model Implementation Example exportMaster Export Rate Model Master in a master data format that can be activated Exports the current Rate Model Master data (both Enhanced Rate Models and Unleash Rate Models) in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRateMaster Rate Model master data that can be activated Implementation Example getCurrentRateMaster Get currently active Rate Model master data Retrieves the master data of the Rate Models (both Enhanced Rate Models and Unleash Rate Models) that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRateMaster Currently active Rate Model master data Implementation Example preUpdateCurrentRateMaster Update Currently Active Rate Model Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentRateMaster Update Currently Active Rate Model Master Data Updates and activates (publishes) the master data of the Rate Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example updateCurrentRateMasterFromGitHub Update Currently Active Rate Model Master Data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example describeRateModelMasters Get a list of Enhanced Rate Model Masters Retrieves a paginated list of editable Enhanced Rate Model Masters with optional name prefix filtering. Enhanced Rate Model Masters are the editable definitions for enhancement rate configurations. Changes to masters do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Enhanced Rate Model name prefix 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 List of Enhanced Rate Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRateModelMaster Create a new Enhanced Rate Master Creates a new editable Enhanced Rate Model Master definition. The rate model defines the target inventory model, material inventory model, experience hierarchy, experience suffix, experience model, and bonus rates. Bonus rates define the probability of experience multipliers being applied during enhancement. Changes do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, if you have metadata like { “aaa”: { “bbb”: { “experienceValue”: 100 } } }, specify [ “aaa”, “bbb”, “experienceValue” ]. Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. Result Type Description item RateModelMaster Enhanced Rate Master created Implementation Example getRateModelMaster Get Enhanced Rate Master Retrieves the detailed information of a specific editable Enhanced Rate Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModelMaster Enhanced Rate Master Implementation Example updateRateModelMaster Update Enhanced Rate Master Updates the description, metadata, target inventory model, material inventory model, experience hierarchy, experience suffix, experience model, and bonus rates of an existing Enhanced Rate Model Master. The rate model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, if you have metadata like { “aaa”: { “bbb”: { “experienceValue”: 100 } } }, specify [ “aaa”, “bbb”, “experienceValue” ]. Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. Result Type Description item RateModelMaster Enhanced Rate Master updated Implementation Example deleteRateModelMaster Delete Enhanced Rate Master Deletes an editable Enhanced Rate Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModelMaster Enhanced Rate Master deleted Implementation Example describeUnleashRateModelMasters Get a list of Unleash Rate Model Masters Retrieves a paginated list of editable Unleash Rate Model Masters with optional name prefix filtering. Unleash Rate Model Masters are the editable definitions for limit break rate configurations. Changes to masters do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Unleash Rate Model name prefix 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 List of Unleash Rate Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createUnleashRateModelMaster Create a new Unleash Rate Model Master Creates a new editable Unleash Rate Model Master definition. The unleash rate model defines the target inventory model, grade model, and grade entries that specify the materials required to raise each grade level. Grade entries map grade values to the material requirements needed for limit breaking to that grade. Changes do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata Any value can be set for metadata. It does not affect the operation of GS2 in any way, and should be used as a storage location for values used in the game. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. Result Type Description item UnleashRateModelMaster Unleash Rate Model Master created Implementation Example getUnleashRateModelMaster Get Unleash Rate Model Master Retrieves the detailed information of a specific editable Unleash Rate Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item UnleashRateModelMaster Unleash Rate Model Master Implementation Example updateUnleashRateModelMaster Update Unleash Rate Model Master Updates the description, metadata, target inventory model, grade model, and grade entries of an existing Unleash Rate Model Master. The unleash rate model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata Any value can be set for metadata. It does not affect the operation of GS2 in any way, and should be used as a storage location for values used in the game. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. Result Type Description item UnleashRateModelMaster Unleash Rate Model Master updated Implementation Example deleteUnleashRateModelMaster Delete Unleash Rate Model Master Deletes an editable Unleash Rate Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item UnleashRateModelMaster Unleash Rate Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Enhance SDK for various programming languages\n","title":"GS2-Enhance SDK API Reference","url":"/api_reference/enhance/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description enableDirectExchange bool true Allow direct exchange API calls When enabled, clients can call the exchange API directly to perform resource exchanges. When disabled, exchanges can only be triggered via transaction actions (transactions), providing tighter server-side control over when exchanges occur. enableAwaitExchange bool false Whether to enable exchanges that require a waiting time before receiving results When enabled, exchange rate models with await timing type can be used. These exchanges require real-time to elapse before rewards can be claimed, enabling crafting or production mechanics where players must wait for the result. transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing exchange operations. Supports auto-run, atomic commit, and async processing options. exchangeScript ScriptSetting Script to run when an attempt is made to perform an exchange Script Trigger Reference - exchange incrementalExchangeScript ScriptSetting Script to run when an attempt is made to perform an incremental exchange Script Trigger Reference - incrementalExchange acquireAwaitScript ScriptSetting Script setting executed when the waiting period completes and the reward is about to be acquired in an await-type exchange Script Trigger Reference - acquireAwait logSetting LogSetting Log Output Setting Configuration for outputting log data of exchange operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for exchange, incremental exchange, and await operations can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Await Exchange Await Represents the execution state of an exchange that requires real-time to elapse before rewards can be claimed. Created when a player initiates an exchange with await timing type, and tracks the waiting period until the rewards become available. Supports skip functionality to shorten or eliminate the waiting time, and stores default configuration values for reward acquisition. Details  awaitId string * ~ 1024 chars Exchange Await A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. count int 1 1 ~ 10000 Number of exchanges The number of times this exchange should be performed. Multiple exchanges can be batched into a single await, multiplying both the cost consumed and the rewards received. skipSeconds int 0 0 ~ 2147483646 Skip seconds The number of seconds to subtract from the waiting time. When skip seconds are applied, the acquirableAt timestamp is moved earlier by this amount. Used to implement mechanics where players can pay resources to speed up the waiting process. config List [] 0 ~ 32 items Default configuration values applied when obtaining rewards Key-value pairs used as transaction placeholder variables when the await completes and rewards are distributed. These values are set at the time of exchange initiation and applied to the acquire actions’ transaction parameters. acquirableAt long Time when rewards can be received The timestamp at which the waiting period expires and rewards become claimable. Calculated as exchangedAt + lockTime - skipSeconds. The player can call the acquire API once the current time has passed this timestamp. exchangedAt long Exchange time The timestamp when the exchange was initiated and the await was created. Used as the base time for calculating when rewards become available (acquirableAt = exchangedAt + lockTime - skipSeconds). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RateModel Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange. Details  rateModelId string * ~ 1024 chars Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Exchange Rate Model name Exchange Rate 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. IncrementalRateModel Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis. Details  incrementalRateModelId string * ~ 1024 chars Incremental Cost Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script Script Trigger Reference - calculateCost * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. LogCost Cost Calculation Result Using Logarithm Represents a cost value computed using logarithmic arithmetic. The final cost is calculated by summing logarithmic values in the adds list and subtracting those in the subs list, then converting back from logarithmic form using the specified base. Used for precise large-number cost calculations that avoid overflow. Details  base double  0 ~ 10 Base The logarithmic base used for the cost calculation. All logarithmic values in the adds and subs lists use this base. Common values include 2, e (approximately 2.718), or 10. adds List  1 ~ 10000 items List of logs to be added Logarithmic values that contribute positively to the final cost. These values are summed in logarithmic form before being converted back to the actual cost value. Equivalent to multiplying the corresponding real values together. subs List 0 ~ 10000 items List of logs to be subtracted Logarithmic values that reduce the final cost. These values are subtracted in logarithmic form, which is equivalent to dividing the corresponding real values from the product of the adds list. LogRate Logarithmic Acquisition Correction Represents a reward quantity correction computed using logarithmic arithmetic. The correction factor is calculated by summing the logarithmic values in the logs list and converting back using the specified base. Used to apply multipliers to acquisition amounts using precise large-number arithmetic. Details  base double  0 ~ 10 Base The logarithmic base used for the acquisition correction calculation. All logarithmic values in the logs list use this base. logs List  1 ~ 10000 items List of logs Logarithmic values that are summed to compute the acquisition correction factor. The sum is converted back from logarithmic form to produce the final multiplier applied to the reward quantity. AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentRateMaster Currently active Rate Model master data This master data defines the Rate Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Exchange Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data RateModelMaster Exchange Rate Model Master Exchange Rate Model Master is data used to edit and manage exchange rate model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as exchange rate model actually referenced by the game. Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to rates that can be exchanged immediately, rates can also be set that can be exchanged after a certain amount of time in real time. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange. Details  rateModelId string * ~ 1024 chars Exchange Rate Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision IncrementalRateModelMaster Incremental Cost Exchange Rate Model Master Incremental Cost Exchange Rate Model Master is data used to edit and manage Incremental Cost Exchange Rate Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Incremental Cost Exchange Rate Model actually referenced by the game. Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis. Details  incrementalRateModelId string * ~ 1024 chars Incremental Cost Exchange Rate Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script Script Trigger Reference - calculateCost * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description enableAwaitExchange bool false Whether to enable exchanges that require a waiting time before receiving results When enabled, exchange rate models with await timing type can be used. These exchanges require real-time to elapse before rewards can be claimed, enabling crafting or production mechanics where players must wait for the result. enableDirectExchange bool true Allow direct exchange API calls When enabled, clients can call the exchange API directly to perform resource exchanges. When disabled, exchanges can only be triggered via transaction actions (transactions), providing tighter server-side control over when exchanges occur. transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing exchange operations. Supports auto-run, atomic commit, and async processing options. exchangeScript ScriptSetting Script to run when an attempt is made to perform an exchange Script Trigger Reference - exchange incrementalExchangeScript ScriptSetting Script to run when an attempt is made to perform an incremental exchange Script Trigger Reference - incrementalExchange acquireAwaitScript ScriptSetting Script setting executed when the waiting period completes and the reward is about to be acquired in an await-type exchange Script Trigger Reference - acquireAwait logSetting LogSetting Log Output Setting Configuration for outputting log data of exchange operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for exchange, incremental exchange, and await operations can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description enableAwaitExchange bool false Whether to enable exchanges that require a waiting time before receiving results When enabled, exchange rate models with await timing type can be used. These exchanges require real-time to elapse before rewards can be claimed, enabling crafting or production mechanics where players must wait for the result. enableDirectExchange bool true Allow direct exchange API calls When enabled, clients can call the exchange API directly to perform resource exchanges. When disabled, exchanges can only be triggered via transaction actions (transactions), providing tighter server-side control over when exchanges occur. transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing exchange operations. Supports auto-run, atomic commit, and async processing options. exchangeScript ScriptSetting Script to run when an attempt is made to perform an exchange Script Trigger Reference - exchange incrementalExchangeScript ScriptSetting Script to run when an attempt is made to perform an incremental exchange Script Trigger Reference - incrementalExchange acquireAwaitScript ScriptSetting Script setting executed when the waiting period completes and the reward is about to be acquired in an await-type exchange Script Trigger Reference - acquireAwait logSetting LogSetting Log Output Setting Configuration for outputting log data of exchange operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for exchange, incremental exchange, and await operations can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example exchange Perform exchange Executes a resource exchange based on the specified Exchange Rate Model. Validates the rate model’s timing type: for ‘immediate’ timing, the namespace must have direct exchange enabled; for ‘await’ timing, the namespace must have await exchange enabled. A transaction (transaction) is issued to execute the consume/verify/acquire actions defined in the rate model, multiplied by the specified count. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item RateModel Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example exchangeByUserId Perform exchange by specifying a user ID Executes a resource exchange based on the specified Exchange Rate Model for the specified user. Validates the rate model’s timing type: for ‘immediate’ timing, the namespace must have direct exchange enabled; for ‘await’ timing, the namespace must have await exchange enabled. A transaction (transaction) is issued to execute the consume/verify/acquire actions defined in the rate model, multiplied by the specified count. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RateModel Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example incrementalExchange Perform incremental cost exchange Executes a resource exchange where the cost increases progressively with each execution, based on the specified Incremental Cost Exchange Rate Model. The consume cost is calculated according to the model’s calculation type (linear formula or GS2-Script) and the current exchange count. A transaction (transaction) is issued to execute the consume and acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). accessToken string  ~ 128 chars Access token count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item IncrementalRateModel Incremental Cost Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example incrementalExchangeByUserId Perform incremental cost exchange by specifying a user ID Executes a resource exchange where the cost increases progressively with each execution, based on the specified Incremental Cost Exchange Rate Model for the specified user. The consume cost is calculated according to the model’s calculation type (linear formula or GS2-Script) and the current exchange count. A transaction (transaction) is issued to execute the consume and acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). userId string  ~ 128 chars User ID count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item IncrementalRateModel Incremental Cost Exchange Rate Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example createAwaitByUserId Create Exchange Await by specifying a user ID Creates a new exchange await record for a time-delayed exchange. The specified rate model must have its timing type set to ‘await’; otherwise the request is rejected. The await starts with zero skip seconds, and the lock time defined in the rate model determines how long the user must wait before acquiring the rewards. Default configuration values can be set at creation time and will be merged with any config provided at acquisition time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). count int 1 1 ~ 10000 Number of exchanges The number of times this exchange should be performed. Multiple exchanges can be batched into a single await, multiplying both the cost consumed and the rewards received. config List [] 0 ~ 32 items Default configuration values applied when obtaining rewards timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await Implementation Example describeAwaits Get a list of Exchange Awaits Retrieves a paginated list of exchange await records for the authenticated user. Optionally filter by rate name to retrieve only awaits for a specific exchange rate. Each await record includes the rate name, exchange count, skip seconds, and timing information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rateName string ~ 128 chars Exchange Rate Model name Exchange Rate 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 List of Exchange Awaits nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeAwaitsByUserId Get a list of Exchange Awaits by specifying a user ID Retrieves a paginated list of exchange await records for the specified user. Optionally filter by rate name to retrieve only awaits for a specific exchange rate. Each await record includes the rate name, exchange count, skip seconds, and timing information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rateName string ~ 128 chars Exchange Rate Model name Exchange Rate 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Exchange Awaits nextPageToken string Page token to retrieve the rest of the listing Implementation Example getAwait Get Exchange Await Retrieves the detailed information of a specific exchange await record for the authenticated user. The returned await includes the rate name, exchange count, current skip seconds, and creation/acquisition timing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. Result Type Description item Await Exchange Await Implementation Example getAwaitByUserId Get Exchange Await by specifying a user ID Retrieves the detailed information of a specific exchange await record for the specified user. The returned await includes the rate name, exchange count, current skip seconds, and creation/acquisition timing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await Implementation Example acquire Receive rewards for Exchange Await Acquires the rewards for a completed exchange await. The await must have passed its lock time (adjusted by any skip seconds) before rewards can be claimed. The provided config values are merged with the default config set at await creation time. A transaction (transaction) is issued to execute the acquire actions defined in the rate model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Await Exchange Await transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward acquisition process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example acquireByUserId Receive rewards for Exchange Await by specifying a user ID Acquires the rewards for a completed exchange await for the specified user. The await must have passed its lock time (adjusted by any skip seconds) before rewards can be claimed. The provided config values are merged with the default config set at await creation time. A transaction (transaction) is issued to execute the acquire actions defined in the rate model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward acquisition process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example acquireForceByUserId Receive rewards for Exchange Await without waiting for the lock time Force-acquires the rewards for an exchange await regardless of whether the lock time has elapsed. This bypasses the normal wait time check, allowing immediate reward acquisition. The provided config values are merged with the default config set at await creation time. A transaction (transaction) is issued to execute the acquire actions defined in the rate model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward acquisition process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example skipByUserId Skip Exchange Await by specifying a user ID Accelerates or skips the waiting time of an exchange await. Supports four skip types: ‘complete’ skips the entire remaining wait, ‘minutes’ adds the specified minutes to skip seconds, ’totalRate’ skips a percentage of the total lock time, and ‘remainRate’ skips a percentage of the remaining wait time. The skip seconds are capped at the total lock time and cannot exceed it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. skipType string (enum) enum {   “complete”,   “minutes”,   “totalRate”,   “remainRate” } “complete” Skip type Definition Description “complete” Complete skip “minutes” Skip by specifying time(minutes) “totalRate” Skip by specifying the percentage of total waiting time “remainRate” Skip by specifying the percentage of remaining waiting time minutes int {skipType} == “minutes” 0 ~ 2147483646 Minutes to skip * Enabled only if skipType is “minutes” rate float {skipType} == “totalRate” or {skipType} == “remainRate” 0 ~ 1 Percentage of time to skip timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await Implementation Example deleteAwait Delete Exchange Await Deletes an exchange await record for the authenticated user. This cancels the pending exchange, and any rewards that have not yet been acquired are forfeited. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. Result Type Description item Await Exchange Await Implementation Example deleteAwaitByUserId Delete Exchange Await by specifying a user ID Deletes an exchange await record for the specified user. This cancels the pending exchange, and any rewards that have not yet been acquired are forfeited. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Await Exchange Await Implementation Example describeRateModels Get a list of Exchange Rate Models Retrieves the list of currently active (published) Exchange Rate Models in the specified namespace. Each Rate Model defines the exchange configuration including timing type (immediate or await), lock time for await exchanges, and the consume/verify/acquire actions that are executed during the exchange. Only models that have been activated via the CurrentRateMaster are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Exchange Rate Models Implementation Example getRateModel Get Exchange Rate Model Retrieves the detailed information of a specific currently active Exchange Rate Model by name. The returned model includes the timing type, lock time, and the consume/verify/acquire actions that define the exchange behavior. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModel Exchange Rate Model Implementation Example describeIncrementalRateModels Get a list of Incremental Cost Exchange Rate Models Retrieves the list of currently active (published) Incremental Cost Exchange Rate Models in the specified namespace. Each model defines an exchange where the cost increases progressively with each execution, including the consume action, calculation type (linear or GS2-Script), base/coefficient values, and acquire actions. Only models that have been activated via the CurrentRateMaster are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Incremental Cost Exchange Rate Models Implementation Example getIncrementalRateModel Get an Incremental Cost Exchange Rate Model Retrieves the detailed information of a specific currently active Incremental Cost Exchange Rate Model by name. The returned model includes the consume action, calculation type, base value, coefficient value, exchange count ID, maximum exchange count, and acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item IncrementalRateModel Incremental Cost Exchange Rate Model Implementation Example exportMaster Export Rate Model Master in a master data format that can be activated Exports the current Rate Model Master data (both Exchange Rate Models and Incremental Cost Exchange Rate Models) in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRateMaster Rate Model master data that can be activated Implementation Example getCurrentRateMaster Get currently active Rate Model master data Retrieves the master data of the Rate Models (both Exchange Rate Models and Incremental Cost Exchange Rate Models) that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRateMaster Currently Active Rate Model Master Data Implementation Example preUpdateCurrentRateMaster Update Currently Active Rate Model Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentRateMaster Update Currently Active Rate Model Master Data Updates and activates (publishes) the master data of the Rate Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example updateCurrentRateMasterFromGitHub Update Currently Active Rate Model Master Data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example describeRateModelMasters Get a list of Exchange Rate Model Masters Retrieves a paginated list of editable Exchange Rate Model Masters with optional name prefix filtering. Exchange Rate Model Masters are the editable definitions for exchange rate configurations. Changes to masters do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by exchange rate name prefix 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 List of Exchange Rate Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRateModelMaster Create a new Exchange Rate Model Master Creates a new editable Exchange Rate Model Master definition. The rate model defines the timing type (‘immediate’ for instant exchange, ‘await’ for time-delayed exchange), lock time for await exchanges, and the consume/verify/acquire actions that are executed during the exchange. Changes do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. Result Type Description item RateModelMaster Exchange Rate Model Master created Implementation Example getRateModelMaster Get Exchange Rate Model Master Retrieves the detailed information of a specific editable Exchange Rate Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModelMaster Exchange Rate Model Master Implementation Example updateRateModelMaster Update Exchange Rate Model Master Updates the description, metadata, timing type, lock time, and consume/verify/acquire actions of an existing Exchange Rate Model Master. The rate model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. Result Type Description item RateModelMaster Exchange Rate Model Master updated Implementation Example deleteRateModelMaster Delete Exchange Rate Model Master Deletes an editable Exchange Rate Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RateModelMaster Exchange Rate Model Master deleted Implementation Example describeIncrementalRateModelMasters Get a list of Incremental Cost Exchange Rate Model Masters Retrieves a paginated list of editable Incremental Cost Exchange Rate Model Masters with optional name prefix filtering. Incremental Cost Exchange Rate Model Masters are the editable definitions for exchanges with progressively increasing costs. Changes to masters do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Incremental Cost Exchange Rate Model name prefix 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 List of Incremental Cost Exchange Rate Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createIncrementalRateModelMaster Create a new Incremental Cost Exchange Rate Model Master Creates a new editable Incremental Cost Exchange Rate Model Master definition. The model defines a consume action whose cost increases based on the calculation type: ’linear’ (baseValue + coefficientValue * exchangeCount) or ‘gs2Script’ (using a custom GS2-Script). The exchange count ID tracks how many times the exchange has been performed, and a maximum exchange count can be set to limit exchanges. Changes do not take effect until the master data is activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. Result Type Description item IncrementalRateModelMaster Incremental Cost Exchange Rate Model Master created Implementation Example getIncrementalRateModelMaster Get Incremental Cost Exchange Rate Model Master Retrieves the detailed information of a specific editable Incremental Cost Exchange Rate Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item IncrementalRateModelMaster Incremental Cost Exchange Rate Model Master Implementation Example updateIncrementalRateModelMaster Update Incremental Cost Exchange Rate Model Master Updates the description, metadata, consume action, calculation type, base/coefficient values, script ID, exchange count ID, maximum exchange count, and acquire actions of an existing Incremental Cost Exchange Rate Model Master. The rate model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentRateMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. Result Type Description item IncrementalRateModelMaster Incremental Cost Exchange Rate Model Master updated Implementation Example deleteIncrementalRateModelMaster Delete Incremental Cost Exchange Rate Model Master Deletes an editable Incremental Cost Exchange Rate Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item IncrementalRateModelMaster Incremental Cost Exchange Rate Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Exchange SDK for various programming languages\n","title":"GS2-Exchange SDK API Reference","url":"/api_reference/exchange/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing experience operations. Supports auto-run, atomic commit, and async processing options. rankCapScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to dynamically determine rank caps Script Trigger Reference - rankCapScript changeExperienceScript ScriptSetting Script setting to be executed when experience value changes Script Trigger Reference - changeExperience changeRankScript ScriptSetting Script setting to be executed when rank changes Script Trigger Reference - changeRank changeRankCapScript ScriptSetting Script setting to be executed when the rank cap changes Script Trigger Reference - changeRankCap overflowExperienceScript string ~ 1024 chars Script GRN to run when experience overflows Script Trigger Reference - overflowExperience logSetting LogSetting Log Output Setting Configuration for outputting log data of experience operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for experience value changes, rank-ups, and rank cap modifications can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Status Status Status is an entity that exists for each property ID. Holds the current experience and rank cap values. Property ID is a status-specific ID and can be set to any value by the developer. For GS2, it is recommended to use a value as the property ID that adds an experience point model suffix to the end of the Item Set GRN in GS2-Inventory or the Entry GRN in GS2-Dictionary that possesses experience points. Details  statusId string * ~ 1024 chars Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Cumulative experience gained The total experience value accumulated by this status. The current rank is derived from this value using the rank threshold table. Experience cannot be gained beyond the threshold corresponding to the current rank cap. rankValue long 0 0 ~ 9223372036854775805 Current Rank The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. nextRankUpExperienceValue long 0 0 ~ 9223372036854775805 Experience points required for the next rank-up The cumulative experience threshold needed to advance to the next rank. Returns 0 if the status has already reached the rank cap. Useful for displaying progress bars or remaining experience in the game UI. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ExperienceModel Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank. Details  experienceModelId string * ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Experience Model name Experience 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThreshold Threshold  Rank Up Threshold References the threshold table that defines the cumulative experience values required for each rank. The number of entries in the threshold determines the maximum possible rank, and each entry’s value specifies the experience needed to reach the next rank. acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. Threshold Rank Up Threshold The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained. Details  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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). AcquireActionRate Reward Addition Table Defines a rank-based multiplier table that adjusts reward quantities based on the status’s current rank. Each entry in the table corresponds to a rank and specifies a multiplier applied to the acquisition amount. Supports both standard double-precision values and big number string representations for large-scale calculations. Details  name string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. mode string (enum) enum {   “double”,   “big” } “double” Reward addition table type Selects the numeric precision for the multiplier values. Use “double” for standard floating-point numbers (up to 2^48), or “big” for string-represented numbers supporting up to 1024 digits when large-scale calculations are needed. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 10000 items Amount added per rank (multiplier) An array of multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 10000 items Amount added per rank (multiplier) An array of string-represented multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “big” for calculations requiring large-number precision. * Required if mode is “big” VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action CurrentExperienceMaster Currently active Experience Model master data This master data defines the Experience Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Experience Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data ExperienceModelMaster Experience Model Master Experience Model Master is data used to edit and manage Experience Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Experience Model actually referenced by the game. An Experience Model is an entity that sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. Details  experienceModelId string * ~ 1024 chars Experience Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ThresholdMaster Rank Up Threshold Master Rank Up Threshold Master is data used to edit and manage Rank Up Threshold within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Rank Up Threshold actually referenced by the game. The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained. Details  thresholdId string * ~ 1024 chars Rank Up Threshold Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing experience operations. Supports auto-run, atomic commit, and async processing options. rankCapScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to dynamically determine rank caps changeExperienceScript ScriptSetting Script setting to be executed when experience value changes Script Trigger Reference - changeExperience changeRankScript ScriptSetting Script setting to be executed when rank changes Script Trigger Reference - changeRank changeRankCapScript ScriptSetting Script setting to be executed when the rank cap changes Script Trigger Reference - changeRankCap overflowExperienceScript string ~ 1024 chars Script GRN to run when experience overflows Script Trigger Reference - overflowExperience logSetting LogSetting Log Output Setting Configuration for outputting log data of experience operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for experience value changes, rank-ups, and rank cap modifications can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing experience operations. Supports auto-run, atomic commit, and async processing options. rankCapScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to dynamically determine rank caps changeExperienceScript ScriptSetting Script setting to be executed when experience value changes Script Trigger Reference - changeExperience changeRankScript ScriptSetting Script setting to be executed when rank changes Script Trigger Reference - changeRank changeRankCapScript ScriptSetting Script setting to be executed when the rank cap changes Script Trigger Reference - changeRankCap overflowExperienceScript string ~ 1024 chars Script GRN to run when experience overflows Script Trigger Reference - overflowExperience logSetting LogSetting Log Output Setting Configuration for outputting log data of experience operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for experience value changes, rank-ups, and rank cap modifications can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeStatuses Get a list of statuses Retrieves a paginated list of the requesting user’s experience statuses. Can optionally filter by experience model name to get statuses only for a specific model. Each status contains the current experience value, rank (calculated from thresholds), and rank cap for a specific property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string ~ 128 chars Experience Model name accessToken string  ~ 128 chars Access token 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStatusesByUserId Get a list of statuses by specifying a user ID Retrieves a paginated list of experience statuses for the specified user. Can optionally filter by experience model name. Each status contains the current experience value, rank, and rank cap for a specific property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string ~ 128 chars Experience Model name userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStatus Get Status Retrieves the experience status for the requesting user, identified by experience model name and property ID. Returns the current experience value, rank (determined by the rank-up thresholds), and rank cap. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. Result Type Description item Status Status Implementation Example getStatusByUserId Get Status by specifying a user ID Retrieves the experience status for the specified user, identified by experience model name and property ID. Returns the current experience value, rank, and rank cap. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example getStatusWithSignature Get status along with signature Retrieves the experience status along with a cryptographic signature generated using the specified encryption key. The signature can be used for secure verification of the status data in external systems or game clients, preventing tampering. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Status Status body string Object to be verified signature string signature Implementation Example getStatusWithSignatureByUserId Get Status with signature by specifying a user ID Retrieves the experience status for the specified user along with a cryptographic signature. The signature is generated using the specified encryption key and can be used for secure verification of the status data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status body string Object to be verified signature string signature Implementation Example addExperienceByUserId Add experience by specifying a user ID Adds experience points to the specified user’s status. Rank is automatically recalculated based on the rank-up threshold values. When truncateExperienceWhenRankUp is true, excess experience beyond the rank-up threshold is discarded on rank up; when false (default), it carries over to the next rank. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Gained Experience truncateExperienceWhenRankUp bool? false Whether to truncate the remaining experience when ranking up timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after addition Implementation Example subExperience Subtract experience Subtracts experience points from the requesting user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Lost Experience Result Type Description item Status Status after subtraction Implementation Example subExperienceByUserId Subtract experience by specifying a user ID Subtracts experience points from the specified user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Lost Experience timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after subtraction Implementation Example setExperienceByUserId Set experience by specifying a user ID Directly sets the experience value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. Rank is automatically recalculated based on the rank-up threshold values. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Cumulative experience gained The total experience value accumulated by this status. The current rank is derived from this value using the rank threshold table. Experience cannot be gained beyond the threshold corresponding to the current rank cap. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated old Status Status before update Implementation Example addRankCapByUserId Add rank cap by specifying a user ID Increases the rank cap of the specified user’s status. The rank cap cannot exceed the maxRankCap defined in the Experience Model. The rank cap determines the maximum rank a user can achieve for the specified property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after addition Implementation Example subRankCap Subtract rank cap Decreases the rank cap of the requesting user’s status. The rank cap will not go below 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. Result Type Description item Status Status after subtraction Implementation Example subRankCapByUserId Subtract rank cap by specifying a user ID Decreases the rank cap of the specified user’s status. The rank cap will not go below 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after subtraction Implementation Example setRankCapByUserId Set rank cap by specifying a user ID Directly sets the rank cap value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. The rank cap is capped at the maxRankCap defined in the Experience Model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated old Status Status before update Implementation Example deleteStatusByUserId Delete status Deletes the experience status for the specified user, experience model, and property. This resets the user’s experience, rank, and rank cap for the specified property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status deleted Implementation Example verifyRank Verify rank Verifies that the requesting user’s current rank satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Used for conditional processing in game logic. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank is less than the specified value “lessEqual” Rank is less than or equal to the specified value “greater” Rank is greater than the specified value “greaterEqual” Rank is greater than or equal to the specified value “equal” Rank is equal to the specified value “notEqual” Rank is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankValue long 0 0 ~ 9223372036854775805 Current Rank The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Status Status updated Implementation Example verifyRankByUserId Verify rank by specifying a user ID Verifies that the specified user’s current rank satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank is less than the specified value “lessEqual” Rank is less than or equal to the specified value “greater” Rank is greater than the specified value “greaterEqual” Rank is greater than or equal to the specified value “equal” Rank is equal to the specified value “notEqual” Rank is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankValue long 0 0 ~ 9223372036854775805 Current Rank The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated Implementation Example verifyRankCap Verify rank cap Verifies that the requesting user’s current rank cap (including buff effects) satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Used for conditional processing in game logic. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank cap is less than the specified value “lessEqual” Rank cap is less than or equal to the specified value “greater” Rank cap is greater than the specified value “greaterEqual” Rank cap is greater than or equal to the specified value “equal” Rank cap is equal to the specified value “notEqual” Rank cap is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Status Status updated Implementation Example verifyRankCapByUserId Verify rank cap by specifying a user ID Verifies that the specified user’s current rank cap (including buff effects) satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank cap is less than the specified value “lessEqual” Rank cap is less than or equal to the specified value “greater” Rank cap is greater than the specified value “greaterEqual” Rank cap is greater than or equal to the specified value “equal” Rank cap is equal to the specified value “notEqual” Rank cap is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated Implementation Example multiplyAcquireActionsByUserId Multiply resources according to the rank of the property subject to the experience value by specifying user ID Looks up the acquire action rate for the specified rateName based on the property’s current rank value, multiplies the specified acquire actions by that rate (combined with baseRate), and starts a transaction to execute the resulting actions. This is used for rank-based reward scaling, where higher ranks earn proportionally more resources. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rateName string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. acquireActions List [] 0 ~ 100 items List of Acquire Actions baseRate float 1 0 ~ 1000000 Base rate timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Rewards transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeExperienceModels Get a list of Experience Models Retrieves all currently active (published) Experience Models in the specified namespace. Experience Models define the configuration for experience/rank systems, including default experience value, default/max rank cap, associated rank-up thresholds, and acquire action rate definitions. These are the models that are actually in use, as opposed to the editable Experience Model Masters. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Experience Model Implementation Example getExperienceModel Get Experience Model Retrieves the detailed information of a specific currently active (published) Experience Model by name. Returns the model’s configuration including default experience value, default/max rank cap, associated rank-up threshold definition, and acquire action rate settings used for rank-based reward scaling. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ExperienceModel Experience Model Implementation Example exportMaster Export Experience Model Master in a master data format that can be activated Exports the current Experience Model Masters and Rank Up Threshold Masters in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentExperienceMaster Experience Model master data that can be activated Implementation Example getCurrentExperienceMaster Get currently active Experience Model master data Retrieves the master data of the Experience Models and Rank Up Thresholds that are currently active (published) in the specified namespace. This represents the configuration that is actually being used in production, as opposed to the editable master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentExperienceMaster Currently active Experience Model master data Implementation Example preUpdateCurrentExperienceMaster Update currently active Experience Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentExperienceMaster Update currently active Experience Model master data Updates and activates (publishes) the master data of the Experience Models and Rank Up Thresholds in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentExperienceMaster Updated master data of the currently active Experience Models Implementation Example updateCurrentExperienceMasterFromGitHub Update currently active Experience Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentExperienceMaster Updated master data of the currently active Experience Models Implementation Example describeExperienceModelMasters Get a list of Experience Model Masters Retrieves a paginated list of editable Experience Model Masters with optional name prefix filtering. Experience Model Masters are the editable definitions for experience/rank systems. Changes to masters do not take effect until the master data is activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Experience Model name prefix 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 List of Experience Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createExperienceModelMaster Create a new Experience Model Master Creates a new editable Experience Model Master definition. The model defines the experience/rank system configuration: defaultExperience (initial experience value), defaultRankCap and maxRankCap (initial and maximum rank cap), rankThresholdName (reference to a Threshold Master defining cumulative experience required for each rank-up), and acquireActionRates (rate multipliers applied to acquire actions based on rank). Changes do not take effect until the master data is activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. Result Type Description item ExperienceModelMaster Experience Model Master created Implementation Example getExperienceModelMaster Get Experience Model Master Retrieves the detailed information of a specific editable Experience Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ExperienceModelMaster Experience Model Master Implementation Example updateExperienceModelMaster Update Experience Model Master Updates the description, metadata, default experience, default/max rank cap, rank threshold reference, and acquire action rates of an existing Experience Model Master. The experience model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. Result Type Description item ExperienceModelMaster Experience Model Master updated Implementation Example deleteExperienceModelMaster Delete Experience Model Master Deletes an editable Experience Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). experienceName string  ~ 128 chars Experience Model name Experience Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ExperienceModelMaster Experience Model Master deleted Implementation Example describeThresholdMasters Get a list of Rank Up Threshold Masters Retrieves a paginated list of editable Rank Up Threshold Masters with optional name prefix filtering. Rank Up Threshold Masters define the cumulative experience values required for each rank-up. They are referenced by Experience Model Masters via the rankThresholdName field. Changes to masters do not take effect until the master data is activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by threshold name prefix 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 List of Rank Up Threshold Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createThresholdMaster Create a new Rank Up Threshold Master Creates a new Rank Up Threshold Master definition with a name and an array of threshold values. The values array defines the cumulative experience required for each rank-up. For example, [100, 300, 600] means rank 1 requires 100 experience, rank 2 requires 300, and rank 3 requires 600. The number of values determines the maximum rank achievable. Changes do not take effect until the master data is activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). Result Type Description item ThresholdMaster Created Rank Up Threshold Master Implementation Example getThresholdMaster Get Rank Up Threshold Master Retrieves the detailed information of a specific editable Rank Up Threshold Master by name. Returns the threshold values array that defines the cumulative experience required for each rank-up. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). thresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ThresholdMaster Rank Up Threshold Master Implementation Example updateThresholdMaster Update Rank Up Threshold Master Updates the description, metadata, and threshold values of an existing Rank Up Threshold Master. The threshold name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentExperienceMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). thresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). Result Type Description item ThresholdMaster Rank Up Threshold Master updated Implementation Example deleteThresholdMaster Delete Rank Up Threshold Master Deletes an editable Rank Up Threshold Master definition. This only affects the master data; the currently active (published) thresholds are not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). thresholdName string  ~ 128 chars Rank Up Threshold name Rank Up Threshold-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ThresholdMaster Rank Up Threshold Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Experience SDK for various programming languages\n","title":"GS2-Experience SDK API Reference","url":"/api_reference/experience/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing formation operations. updateMoldScript ScriptSetting Script to run when updating Mold capacity Script Trigger Reference - updateMold updateFormScript ScriptSetting Script to run when updating a form Script Trigger Reference - updateForm updatePropertyFormScript ScriptSetting Script to run when updating a property form Script Trigger Reference - updatePropertyForm logSetting LogSetting Log Output Setting Configuration for outputting log data of formation operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for form updates, mold capacity changes, and property form modifications can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Mold Form Storage Area An entity that holds information organized by the game player. Form information can be stored multiple times per Form Storage Area, and the capacity—how many can be stored—can be set individually for each game player × Form Storage Area. Details  moldId string * ~ 1024 chars Form Storage Area A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Form Form An entity representing formation status. Slots can be defined as areas that can be formed. For weapons and armor, slots can be represented as parts like “right hand”, “left hand”, “torso”, and “arms”. For parties, slots can be represented as positions like “front line”, “mid-line”, and “back line”. Details  formId string * ~ 1024 chars Form A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form name The name of the mold model this form belongs to. Identifies which form model (slot configuration) applies to this form instance. index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List 0 ~ 10 items List of Slots The current slot assignments for this form. Each entry corresponds to a slot defined in the form model and holds the property ID of the resource assigned to that position. Slot names must match those defined in the form model. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision PropertyForm Property Form An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment. Details  formId string * ~ 1024 chars Property Form A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID name string  ~ 128 chars Property Form name The name of the property form model that defines the slot configuration for this property form. Determines which slots are available for assignment. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List 0 ~ 10 items List of Slots The current slot assignments for this property form. Each entry corresponds to a slot defined in the property form model. For example, if the property form represents skill configuration for a piece of equipment, each slot might hold a different skill assignment. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision FormModel Form Model Form Model is an entity representing the configuration status. You can define slots as areas that can be formed. For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots. Details  formModelId string * ~ 1024 chars Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Model name Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. MoldModel Form Storage Area Model If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually. Details  moldModelId string * ~ 1024 chars Form Storage Area A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Storage Area Model name Form Storage Area 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. initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. formModel FormModel  Form Model PropertyFormModel Property Form Model An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment. Details  propertyFormModelId string * ~ 1024 chars Property Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Property Form Model name Property Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. SlotModel Slot Model Defines a single slot within a form model. A slot represents an assignable position where a game resource (such as an item, character, or equipment) can be placed. The property regex validates what values can be assigned to the slot. Details  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyRegex string “.*” ~ 512 chars Regular expressions for values that can be set as properties A regex pattern that validates the property ID values assignable to this slot. For example, restricting to specific GS2-Inventory item GRNs or GS2-Dictionary entry GRNs. Defaults to “.*” which allows any value. metadata string ~ 512 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. Slot Slot Represents the actual assignment state of a single slot within a form. Each slot holds a property ID referencing the game resource (such as a GS2-Inventory item set or GS2-Dictionary entry) that the player has placed in that position. Details  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyId string ~ 1024 chars Property ID A developer-defined identifier referencing the game resource assigned to this slot. Typically a GS2-Inventory Item Set GRN, GS2-Dictionary Entry GRN, or other resource identifier. Must match the slot model’s propertyRegex pattern. metadata string ~ 1024 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. SlotWithSignature Signature Slot A slot assignment that includes a cryptographic signature proving the player owns the referenced resource. Used when updating forms to verify that the player actually possesses the item, entry, or other resource being placed in the slot, preventing unauthorized assignments. Details  name string  ~ 128 chars Slot Model name Slot Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyType string (enum) enum {   “gs2_inventory”,   “gs2_simple_inventory”,   “gs2_dictionary” }  Property Type Specifies the type of GS2 resource referenced by this slot. Determines how the signature is verified: GS2-Inventory item sets, GS2-Inventory simple items, or GS2-Dictionary entries each have different signature formats. Definition Description “gs2_inventory” GS2-Inventory::ItemSet “gs2_simple_inventory” GS2-Inventory::SimpleItem “gs2_dictionary” GS2-Dictionary::Entry body string ~ 1048576 chars Payload The serialized resource data obtained from the GS2 service that owns the resource. Contains the resource state information needed to verify the signature and confirm ownership. signature string ~ 1024 chars Signature that proves ownership of the resource referenced by the property ID A cryptographic signature generated by the GS2 service that owns the resource. Verified during form updates to ensure the player possesses the referenced item set, simple item, or dictionary entry. metadata string ~ 1024 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. AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentFormMaster Currently active Form Model master data This master data defines the Form Model currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Formation Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data FormModelMaster Form Model Master Form Model Master is data used to edit and manage Form Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Form Model actually referenced by the game. Form Model is an entity representing the configuration status. You can define slots as areas that can be formed. For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots. Details  formModelId string * ~ 1024 chars Form Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Model name Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision MoldModelMaster Form Storage Area Model Master Form Storage Area Model Master is data used to edit and manage Form Storage Area Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Form Storage Area Model actually referenced by the game. If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually. Details  moldModelId string * ~ 1024 chars Form Storage Area Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. formModelName string  ~ 128 chars Form Model name createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision PropertyFormModelMaster Property Form Model Master Property Form Model Master is data used to edit and manage Property Form Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Property Form Model actually referenced by the game. An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment. Details  propertyFormModelId string * ~ 1024 chars Property Form Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing formation operations. updateMoldScript ScriptSetting Script to run when updating Mold capacity Script Trigger Reference - updateMold updateFormScript ScriptSetting Script to run when updating a form Script Trigger Reference - updateForm updatePropertyFormScript ScriptSetting Script to run when updating a property form Script Trigger Reference - updatePropertyForm logSetting LogSetting Log Output Setting Configuration for outputting log data of formation operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for form updates, mold capacity changes, and property form modifications can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing formation operations. updateMoldScript ScriptSetting Script to run when updating Mold capacity Script Trigger Reference - updateMold updateFormScript ScriptSetting Script to run when updating a form Script Trigger Reference - updateForm updatePropertyFormScript ScriptSetting Script to run when updating a property form Script Trigger Reference - updatePropertyForm logSetting LogSetting Log Output Setting Configuration for outputting log data of formation operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for form updates, mold capacity changes, and property form modifications can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeMolds Get a list of Form Storage Areas Retrieves a paginated list of the requesting user’s form storage areas (molds). Each mold represents a user’s storage area for a specific mold model and contains the current capacity information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Form Storage Area nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeMoldsByUserId Get a list of Form Storage Areas by specifying a user ID Retrieves a paginated list of form storage areas (molds) for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Form Storage Area nextPageToken string Page token to retrieve the rest of the listing Implementation Example getMold Get Form Storage Area Retrieves a specific form storage area (mold) for the requesting user by mold model name. Returns the mold with its current capacity and the associated mold model information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Mold Form Storage Area moldModel MoldModel Form Storage Area Implementation Example getMoldByUserId Get Form Storage Area by specifying a user ID Retrieves a specific form storage area (mold) for the specified user by mold model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mold Form Storage Area moldModel MoldModel Form Storage Area Implementation Example setMoldCapacityByUserId Set capacity size with specified user ID Directly sets the capacity of the form storage area (mold) for the specified user to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated mold. The capacity is capped at the maxCapacity defined in the Mold Model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mold Form Storage Area with updated capacity old Mold Form Storage Area before updating capacity moldModel MoldModel Form Storage Area Implementation Example addMoldCapacityByUserId Add capacity size by specifying a user ID Increases the capacity of the form storage area (mold) for the specified user. The capacity cannot exceed the maxCapacity defined in the Mold Model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mold Form Storage Area with updated capacity moldModel MoldModel Form Storage Area Implementation Example subMoldCapacity Subtract capacity size Decreases the capacity of the form storage area (mold) for the requesting user. The capacity will not go below 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. Result Type Description item Mold Form Storage Area with updated capacities moldModel MoldModel Form Storage Area Implementation Example subMoldCapacityByUserId Subtract capacity size by specifying a user ID Decreases the capacity of the form storage area (mold) for the specified user. The capacity will not go below 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mold Form Storage Area with updated capacities moldModel MoldModel Form Storage Area Implementation Example deleteMold Delete Form Storage Area Deletes the form storage area (mold) for the requesting user. This removes all forms stored within the mold along with the capacity data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Mold Form Storage Area Implementation Example deleteMoldByUserId Delete Form Storage Area by specifying a user ID Deletes the form storage area (mold) for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mold Form Storage Area Implementation Example describeForms Get a list of Forms Retrieves a paginated list of the requesting user’s forms within the specified mold (form storage area). Each form contains a set of slots that can hold references to items from inventory, simple inventory, or dictionary. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name accessToken string  ~ 128 chars Access token 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 List of Form nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeFormsByUserId Get a list of Forms by specifying a user ID Retrieves a paginated list of forms for the specified user within the specified mold. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Form nextPageToken string Page token to retrieve the rest of the listing Implementation Example getForm Get Form Retrieves a specific form by mold model name and index for the requesting user. Returns the form along with the associated mold, mold model, and form model information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example getFormByUserId Get Form by specifying a user ID Retrieves a specific form for the specified user by mold model name and index. Returns the form along with the associated mold, mold model, and form model information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example getFormWithSignature Retrieve signed forms Retrieves a form along with a cryptographic signature generated using the specified encryption key. The form data is serialized to JSON and signed, allowing the client to verify the integrity of the form data. The signature can be used when updating the form via SetFormWithSignature to ensure slot contents have not been tampered with. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Form Form body string Value to be signed signature string Signature mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example getFormWithSignatureByUserId Get signed Form by specifying a user ID Retrieves a form for the specified user along with a cryptographic signature. The signature is generated using the specified encryption key and can be used for secure verification. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Form Form body string Value to be signed signature string Signature mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example setForm Set form Updates the slot values of a form for the requesting user. Slots define which items are placed in each position of the form. This is the raw version without signature verification. Use SetFormWithSignature for client-side updates with tamper protection. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List  1 ~ 10 items List of Slots Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example setFormByUserId Set form by specifying a user ID Updates the slot values of a form for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List  1 ~ 10 items List of Slots timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example setFormWithSignature Update forms with signed slots Updates form slots with signature verification for tamper protection. Each slot must include a body and signature that are verified against the encryption key. Supports three property types for slot content: gs2_inventory (extracts ItemSetId), gs2_simple_inventory (extracts ItemId), and gs2_dictionary (extracts EntryId). After verification, the validated slots are applied to the form. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List  1 ~ 10 items List of Slot keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example acquireActionsToFormProperties Apply acquire action to Form Properties by specifying a user ID Applies an acquire action to the form’s slot properties and starts a transaction to execute it. This is used to grant items or resources to the slots of a form, with optional config parameters for customization. Returns a transaction for transaction processing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. acquireAction AcquireAction  Get action to be applied to form properties config List [] 0 ~ 1000 items List of Acquisition config timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Form Form mold Mold Form Storage Area transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example deleteForm Delete form Deletes a form for the requesting user at the specified mold model and index. This removes all slot data associated with the form. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example deleteFormByUserId Delete Form by specifying a user ID Deletes a form for the specified user at the specified mold model and index. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Form Form mold Mold Form Storage Area moldModel MoldModel Form Storage Area Model formModel FormModel Form Model Implementation Example describePropertyForms Get a list of Property Forms Retrieves a paginated list of the requesting user’s property forms for the specified property form model. Property forms are similar to forms but are identified by a custom property ID (e.g., a character ID) rather than an index within a mold. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model 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 List of PropertyForm nextPageToken string Page token to retrieve the rest of the listing Implementation Example describePropertyFormsByUserId Get a list of Property Forms by specifying a user ID Retrieves a paginated list of property forms for the specified user and property form model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of PropertyForm nextPageToken string Page token to retrieve the rest of the listing Implementation Example getPropertyForm Get Property Form Retrieves a specific property form for the requesting user by property form model name and property ID. The property ID is normalized before retrieval. Returns the property form along with the associated property form model information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. Result Type Description item PropertyForm PropertyForm propertyFormModel PropertyFormModel Form Model Implementation Example getPropertyFormByUserId Get Property Form by specifying a user ID Retrieves a specific property form for the specified user by property form model name and property ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PropertyForm PropertyForm propertyFormModel PropertyFormModel Form Model Implementation Example getPropertyFormWithSignature Retrieve signed Property Forms Retrieves a property form along with a cryptographic signature generated using the specified encryption key. The signature can be used when updating the property form via SetPropertyFormWithSignature to ensure slot contents have not been tampered with. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item PropertyForm Property Form body string Value to be signed signature string Signature propertyFormModel PropertyFormModel Property Form Model Implementation Example getPropertyFormWithSignatureByUserId Get signed property form by specifying a user ID Retrieves a property form for the specified user along with a cryptographic signature. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PropertyForm Property Form body string Value to be signed signature string Signature propertyFormModel PropertyFormModel Property Form Model Implementation Example setPropertyForm Update Property Form Updates the slot values of a property form for the requesting user. This is the raw version without signature verification. Use SetPropertyFormWithSignature for client-side updates with tamper protection. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List  1 ~ 10 items List of Slots Result Type Description item PropertyForm Property Form propertyFormModel PropertyFormModel Property Form Model Implementation Example setPropertyFormByUserId Update Property Form by specifying a user ID Updates the slot values of a property form for the specified user (server-side operation). This is the raw version without signature verification, intended for server-side use where the caller is trusted. Each slot holds a reference to a property from another service (inventory, simple inventory, or dictionary). The property form is identified by a custom propertyId (e.g., a character ID) rather than an index within a mold. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List  1 ~ 10 items List of Slots timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PropertyForm Property Form propertyFormModel PropertyFormModel Property Form Model Implementation Example setPropertyFormWithSignature Update Property Form with signed slots Updates the slot values of a property form with cryptographic signature verification for tamper protection. Each slot includes a body and signature pair. The server verifies each slot’s signature using the specified encryption key before applying the update. Supports three property types based on the slot’s property ID prefix: gs2_inventory: references an ItemSet from the Inventory service gs2_simple_inventory: references an Item from the Simple Inventory service gs2_dictionary: references an Entry from the Dictionary service This is the recommended method for client-side updates as it prevents users from setting arbitrary values in form slots. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. slots List  1 ~ 10 items List of Slot keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item PropertyForm Property Form proeprtyFormModel PropertyFormModel Property Form Model Implementation Example acquireActionsToPropertyFormProperties Apply acquire action to property form properties Applies an acquire action to the properties of a property form, initiating a transaction. This is used to grant items or resources that are then set as slot values in the property form. The acquire action is executed as a transaction, and the resulting items are applied to the form’s slot properties. Configuration values can be passed to customize the acquire action behavior. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. acquireAction AcquireAction  Get action to be applied to form properties config List [] 0 ~ 1000 items List of Acquisition config timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PropertyForm Property Form transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example deletePropertyForm Delete Property Form Deletes the property form identified by the specified property form model name and propertyId for the requesting user. Once deleted, all slot values associated with the property form are removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. Result Type Description item PropertyForm Property Form propertyFormModel PropertyFormModel Property Form Model Implementation Example deletePropertyFormByUserId Delete Property Form by specifying a user ID Deletes the property form identified by the specified property form model name and propertyId for the specified user (server-side operation). Once deleted, all slot values associated with the property form are removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PropertyForm Property Form propertyFormModel PropertyFormModel Property Form Model Implementation Example getFormModel Get Form Model Retrieves the currently active (published) Form Model associated with the specified Mold Model. The Form Model defines the slot structure (available slots and their configurations) used by forms within the mold. This is the published model actually in use, as opposed to the editable Form Model Master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item FormModel Form Implementation Example describeMoldModels Get a list of Form Storage Area Models Retrieves all currently active (published) Form Storage Area Models (Mold Models) in the specified namespace. Each model defines the form model to use, initial max capacity, and absolute max capacity for form storage areas. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Form Storage Areas Implementation Example getMoldModel Get Form Storage Area Model Retrieves a specific currently active (published) Form Storage Area Model (Mold Model) by name. Returns the model’s configuration including the associated form model name, initial max capacity, and absolute max capacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MoldModel Form Storage Area Implementation Example describePropertyFormModels Get a list of Property Form Models Retrieves all currently active (published) Property Form Models in the specified namespace. Property Form Models define the slot structure for property forms, which are identified by a custom property ID rather than an index within a mold. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Property Form Model name Implementation Example getPropertyFormModel Get Property Form Model Retrieves a specific currently active (published) Property Form Model by name. Returns the model’s slot structure definition used by property forms of this type. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PropertyFormModel Property Form Implementation Example exportMaster Export Form Model Master in a master data format that can be activated Exports the current Form Model Masters, Form Storage Area Masters (Mold Model Masters), and Property Form Model Masters in a format that can be used for activation. The exported data can be used to back up the current master configuration, or to import it into another namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentFormMaster Form Model master data that can be activated Implementation Example getCurrentFormMaster Get currently active Form Model master data Retrieves the master data of the Form Models, Form Storage Area Models, and Property Form Models that are currently active (published) in the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentFormMaster Currently active Form Model master data Implementation Example preUpdateCurrentFormMaster Update Currently active Form Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentFormMaster Update currently active Form Model master data Updates and activates (publishes) the master data of the Form Models, Form Storage Area Models, and Property Form Models in the specified namespace. Supports two modes: ‘direct’ mode for inline master data, and ‘preUpload’ mode for master data that was uploaded in advance. For master data larger than 1MB, use the 3-phase update flow: PreUpdate -\u003e Upload -\u003e Update (preUpload mode). The uploaded master data is validated before being applied. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentFormMaster Updated master data of the currently active Form Models Implementation Example updateCurrentFormMasterFromGitHub Update currently active Form Model master data from GitHub Updates and activates (publishes) the master data by fetching it directly from a GitHub repository. The checkout settings specify the repository, branch/tag, and file path to use. This is useful for managing master data in version control and deploying it directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentFormMaster Updated master data of the currently active Form Models Implementation Example describeFormModelMasters Get a list of Form Model Masters Retrieves a paginated list of editable Form Model Masters with optional name prefix filtering. Form Model Masters define the slot structure for forms. Changes to masters do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Form Model name prefix 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 List of Form Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createFormModelMaster Create a new Form Model Master Creates a new editable Form Model Master definition with a name and slot definitions. Each slot defines a named position in the form where items (from inventory, simple inventory, or dictionary) can be placed. Changes do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Form Model name Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. Result Type Description item FormModelMaster Form Model Master created Implementation Example getFormModelMaster Get Form Model Master Retrieves the detailed information of a specific editable Form Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). formModelName string  ~ 128 chars Form Model name Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item FormModelMaster Form Model Master Implementation Example updateFormModelMaster Update Form Model Master Updates the description, metadata, and slot definitions of an existing Form Model Master. The form model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). formModelName string  ~ 128 chars Form Model name Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. Result Type Description item FormModelMaster Form Model Master updated Implementation Example deleteFormModelMaster Delete Form Model Master Deletes an editable Form Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). formModelName string  ~ 128 chars Form Model name Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item FormModelMaster Form Model Master deleted Implementation Example describeMoldModelMasters Get a list of Form Storage Area Masters Retrieves a paginated list of editable Form Storage Area Masters (Mold Model Masters) with optional name prefix filtering. Changes to masters do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Form Storage Area name prefix 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 List of Form Storage Area Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createMoldModelMaster Create a new Form Storage Area Master Creates a new editable Form Storage Area Master (Mold Model Master) definition. Defines the form model to use (formModelName), initial max capacity (initialMaxCapacity) assigned to users when first accessing the mold, and the absolute max capacity (maxCapacity) that can be reached via capacity additions. Changes do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. formModelName string  ~ 128 chars Form Model name initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. Result Type Description item MoldModelMaster Form Storage Area Master created Implementation Example getMoldModelMaster Get Form Storage Area Master Retrieves the detailed information of a specific editable Form Storage Area Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MoldModelMaster Form Storage Area Master Implementation Example updateMoldModelMaster Update Form Storage Area Master Updates the description, metadata, form model reference, initial max capacity, and max capacity of an existing Form Storage Area Master. The mold model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. formModelName string  ~ 128 chars Form Model name initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. Result Type Description item MoldModelMaster Form Storage Area Master updated Implementation Example deleteMoldModelMaster Delete Form Storage Area Master Deletes an editable Form Storage Area Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MoldModelMaster Form Storage Area Master deleted Implementation Example describePropertyFormModelMasters Get a list of Property Form Model Masters Retrieves a paginated list of editable Property Form Model Masters with optional name prefix filtering. Property Form Model Masters define the slot structure for property forms. Changes to masters do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Property Form Model name prefix 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 List of Form Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createPropertyFormModelMaster Create a new Property Form Model Master Creates a new editable Property Form Model Master definition with a name and slot definitions. Property Form Models are similar to Form Models but are used for property forms, which are identified by a custom property ID rather than an index within a mold. Changes do not take effect until the master data is activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. Result Type Description item PropertyFormModelMaster Form Model Master created Implementation Example getPropertyFormModelMaster Get Property Form Model Master Retrieves the detailed information of a specific editable Property Form Model Master by name. This is used for viewing and editing the master definition before activation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PropertyFormModelMaster Form Model Master Implementation Example updatePropertyFormModelMaster Update Property Form Model Master Updates the description, metadata, and slot definitions of an existing Property Form Model Master. The property form model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentFormMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form. Result Type Description item PropertyFormModelMaster Form Model Master updated Implementation Example deletePropertyFormModelMaster Delete Property Form Model Master Deletes an editable Property Form Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyFormModelName string  ~ 128 chars Property Form Model name Property Form Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PropertyFormModelMaster Form Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Formation SDK for various programming languages\n","title":"GS2-Formation SDK API Reference","url":"/api_reference/formation/sdk/"},{"content":"Models Output Output of stage update progress Represents a log entry generated during a stage version update operation. Each output captures a step or event in the update process. Outputs are automatically cleaned up after 30 days. Details  outputId string * ~ 1024 chars Stage update progress output A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Output Name Maintains a unique name for each output of stage update progress. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each output of stage update progress. text string  ~ 1048576 chars Text The log message content describing a specific step or event during the stage update process. May contain status information, error details, or progress indicators for the version transition operation. createdAt long * Current time Timestamp revision long 0 0 ~ 9223372036854775805 Revision Stage Stage A stage is an environment information that fixes the program version. You can have multiple stages for one project. A stage has a source stage, and it is possible to switch to the version fixed by the source stage. By using this mechanism, you can first incorporate the latest version into the dev stage and check the operation at the developer level. If there seems to be no problem, the dev stage can be reflected in the stg stage, which has the dev stage as the source stage. After QA, the stg stage can be reflected in the live stage, which has the stg stage as the source stage. Details  stageId string * ~ 1024 chars Stage A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). sourceStageName string ~ 128 chars Source Stage name The name of the stage from which this stage pulls its version configuration. When updating, the versions pinned by the source stage are adopted. For example, a “stg” stage might have “dev” as its source, and “live” might have “stg”. If not specified, the latest versions are used directly. sortNumber int  0 ~ 100 Sort number A numeric value used to control the display order of stages. Lower numbers are displayed first. Useful for arranging stages in a logical progression (e.g., dev=0, stg=50, live=100). status string (enum) enum {   “Active”,   “Updating”,   “UpdateFailed” } “Active” Status The current state of the stage. “Active” indicates normal operation with pinned versions serving requests. “Updating” indicates a version transition is in progress. “UpdateFailed” indicates the version update encountered an error and may require manual intervention. Definition Description “Active” Active “Updating” Updating “UpdateFailed” Update Failed createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Microservice Microservice Represents a GS2 microservice component. Each microservice has a name and version that can be pinned to a specific stage. Details  name string  ~ 128 chars Microservice name The identifier for this microservice. version string  ~ 32 chars Microservice version The version identifier of this microservice. Used to pin the microservice to a specific version during stage deployment, ensuring consistent behavior across environments. Methods describeOutputs Get a list of stage update progress outputs Retrieves a paginated list of output log entries for a specific stage’s update operations (promote/rollback). Output entries are created at each step of the promote or rollback process, including start, step completion, and final success or failure messages. This API can be used to monitor the progress of ongoing deployments. Details Request  stageName string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). 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 List of Output of stage update progress nextPageToken string Page token to retrieve the rest of the listing Implementation Example getOutput Get stage update progress output Retrieves a specific output log entry for a stage’s update operation. Each output entry contains a text message describing what occurred at that point in the promote or rollback process. Details Request  stageName string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). outputName string  UUID ~ 36 chars Output Name Maintains a unique name for each output of stage update progress. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each output of stage update progress. Result Type Description item Output Output Implementation Example describeStages Get a list of stages Retrieves a list of deployment stages owned by the requesting user. Each stage represents an environment (e.g., development, staging, production) with its own microservice version configuration. Details Request  Result Type Description items List List of Stage Implementation Example getStage Get stage Retrieves detailed information about a specific deployment stage, including the source microservice versions (from the previous stage) and the currently deployed microservice versions. The source versions represent the version configuration that would be applied on the next promotion, while the current versions represent what is actually deployed. Details Request  stageName string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). Result Type Description item Stage Stage source List List of version of source microservices current List List of current version of microservices Implementation Example promoteStage Promote stage Applies the microservice versions from the source stage to this stage, initiating an asynchronous deployment process. The stage status changes to Updating during the process, and returns to Active on success or UpdateFailed on failure. Progress can be monitored via the Output API. Details Request  stageName string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). Result Type Description item Stage Stage updated Implementation Example rollbackStage Rollback stage Reverts the stage to the previously deployed microservice versions, initiating an asynchronous rollback process. The stage status changes to Updating during the process, and returns to Active on success or UpdateFailed on failure. Progress can be monitored via the Output API. Details Request  stageName string  ~ 128 chars Stage name The identifier for this stage environment (e.g., “dev”, “stg”, “live”). Result Type Description item Stage Stage updated Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Freeze SDK for various programming languages\n","title":"GS2-Freeze SDK API Reference","url":"/api_reference/freeze/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing friend operations. followScript ScriptSetting Script to run when followed Script Trigger Reference - follow unfollowScript ScriptSetting Script to run when unfollowed Script Trigger Reference - unfollow sendRequestScript ScriptSetting Script to run when a friend request is issued Script Trigger Reference - sendRequest cancelRequestScript ScriptSetting Script to execute when a friend request is canceled Script Trigger Reference - cancelRequest acceptRequestScript ScriptSetting Script to run when a friend request is accepted Script Trigger Reference - acceptRequest rejectRequestScript ScriptSetting Script to execute when a friend request is rejected Script Trigger Reference - rejectRequest deleteFriendScript ScriptSetting Script to run when a friend is deleted Script Trigger Reference - deleteFriend updateProfileScript ScriptSetting Script to run when a profile is updated Script Trigger Reference - updateProfile followNotification NotificationSetting Push notification when followed Configuration for sending a push notification to a player when another player starts following them. Allows the followed player to be notified in real time via GS2-Gateway. receiveRequestNotification NotificationSetting  Push notification when a friend request is received Configuration for sending a push notification to a player when they receive a friend request from another player. Enables the recipient to respond promptly via GS2-Gateway. cancelRequestNotification NotificationSetting  Push notification when a received friend request is canceled Configuration for sending a push notification to a player when a friend request they previously received is canceled by the sender. Notifies the recipient that the pending request no longer exists. acceptRequestNotification NotificationSetting  Push notification when a friend request is approved Configuration for sending a push notification to a player when their sent friend request is accepted by the recipient. Both players are then added to each other’s friend lists. rejectRequestNotification NotificationSetting  Push notification when a friend request is rejected Configuration for sending a push notification to a player when their sent friend request is rejected by the recipient. The friend request is removed from both the send box and inbox. deleteFriendNotification NotificationSetting  Push notification when a friend is deleted Configuration for sending a push notification to a player when they are removed from another player’s friend list. The friendship is terminated for both sides. logSetting LogSetting Log Output Setting Configuration for outputting log data of friend operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for follow/unfollow, friend requests, and profile updates can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Profile Profile The profile stores information about the game player. There are three types of profiles that can be set for each public range. friend The information that can be viewed by those with whom a friend relationship has been established. follow Content that can be viewed by followers. public Content that can be viewed by anyone Details  profileId string * ~ 1024 chars Profile A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Follow Follow A follow is a unidirectional relationship between game players. The relationship is established immediately upon sending a follow request. Details  followId string * ~ 1024 chars Follow A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID targetUserIds List 0 ~ 1000 items List of user IDs that the user follows The list of user IDs that this user is following. Unlike friend relationships, follows are unidirectional and established immediately without requiring approval from the target user. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Friend Friend A friend is a two-way, approved relationship between game players. To establish a friend relationship, one party must send a request and the other party must approve it. Details  friendId string * ~ 1024 chars Friend A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID targetUserIds List 0 ~ 1000 items User ID list of friends The list of user IDs with whom this user has an established mutual friend relationship. Both users must have gone through the friend request approval process. Removing a friend removes the entry from both users’ lists. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SendBox Send Box Manages the list of outgoing friend requests sent by a player. When a player sends a friend request, the target user ID is added to this send box. The sender can cancel a pending request. Duplicate requests to the same user or requests to existing friends are rejected. When the target accepts or rejects, the entry is removed from this send box. Details  sendBoxId string * ~ 1024 chars Friend Request Send Box A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID targetUserIds List 0 ~ 1000 items Destination user ID list for friend requests The user IDs of players to whom this user has sent pending friend requests. Each entry represents an outgoing request awaiting the target’s response. Duplicate entries and requests to existing friends are prevented. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Inbox Inbox Manages the list of received friend requests for a player. When another player sends a friend request, their user ID is added to this inbox. The player can then accept or reject each request. Duplicate requests from the same user or requests from existing friends are rejected. Accepting a request removes it from the inbox and adds both users to each other’s friend lists. Details  inboxId string * ~ 1024 chars Friend Request Inbox A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID fromUserIds List 0 ~ 1000 items List of user IDs who have sent friend requests The user IDs of players who have sent pending friend requests to this user. Each entry represents an unanswered request that can be accepted or rejected. Duplicate entries and requests from existing friends are prevented. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BlackList Blacklist Manages a list of users that the player has blocked. Blocked users are prevented from sending friend requests or follow requests to this player, providing a mechanism for players to control unwanted interactions. Details  blackListId string * ~ 1024 chars Blacklist A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID targetUserIds List 0 ~ 1000 items Blacklist user ID list The list of user IDs that this player has blocked. Blocked users cannot send friend requests or follow requests to this player. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision FollowUser Follow User Represents a user that the current user is following. Provides access to the followed user’s public profile and follower-level profile information, which is visible to followers but not to the general public. Details  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The followed user’s publicly visible profile information, accessible to all players. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to followers. It can contain more detailed information than the public profile. FriendUser Friend User Represents a user who has an established mutual friend relationship with the current user. Provides access to the friend’s public profile and friend-level profile information, which is only visible to confirmed friends. Details  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The friend’s publicly visible profile information, accessible to all players. friendProfile string ~ 1024 chars Profile for friends The friend’s profile information visible only to confirmed friends. Contains more private information than the public profile. FriendRequest Friend Request Represents a friend request between two players. Contains the sender’s user ID, the recipient’s user ID, and the sender’s public profile for display purposes. Details  userId string  ~ 128 chars User ID of the sender of the friend request targetUserId string  ~ 128 chars User ID to whom a friend request was sent publicProfile string ~ 1024 chars Public profile The public profile of the friend request sender. Included for display purposes so that the recipient can identify who is requesting friendship. SendFriendRequest Sent Friend Request This entity indicates the status of a pending Friend Request. This is a Friend Request sent by the user to another user. When the user who sent the Friend Request approves it, the Friend Request is deleted and the user is added to the friend list. Details  userId string  ~ 128 chars User ID of the sender of the friend request targetUserId string  ~ 128 chars User ID to whom a friend request was sent publicProfile string ~ 1024 chars Public profile The public profile of the target user who received this friend request. Allows the sender to view basic information about the recipient. ReceiveFriendRequest Received Friend Request This entity indicates that a friend request has been accepted. This is a Friend Request received by the user from another user. When the user approves the friend request, the friend request is deleted and the user is added to the friend list. Details  userId string  ~ 128 chars User ID of the sender of the friend request targetUserId string  ~ 128 chars User ID to whom a friend request was sent publicProfile string ~ 1024 chars Public profile The public profile of the user who sent this friend request. Allows the recipient to see who is requesting to be friends before accepting or rejecting. PublicProfile Public Profile A read-only view of a user’s publicly visible profile information. Can be retrieved for any user without requiring a friend or follow relationship. Used for displaying player information in search results, leaderboards, or other public contexts. Details  userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile The user’s publicly visible profile content, accessible without requiring a friend or follow relationship. Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing friend operations. followScript ScriptSetting Script to run when followed Script Trigger Reference - follow unfollowScript ScriptSetting Script to run when unfollowed Script Trigger Reference - unfollow sendRequestScript ScriptSetting Script to run when a friend request is issued Script Trigger Reference - sendRequest cancelRequestScript ScriptSetting Script to execute when a friend request is canceled Script Trigger Reference - cancelRequest acceptRequestScript ScriptSetting Script to run when a friend request is accepted Script Trigger Reference - acceptRequest rejectRequestScript ScriptSetting Script to execute when a friend request is rejected Script Trigger Reference - rejectRequest deleteFriendScript ScriptSetting Script to run when a friend is deleted Script Trigger Reference - deleteFriend updateProfileScript ScriptSetting Script to run when a profile is updated Script Trigger Reference - updateProfile followNotification NotificationSetting Push notification when followed Configuration for sending a push notification to a player when another player starts following them. Allows the followed player to be notified in real time via GS2-Gateway. receiveRequestNotification NotificationSetting  Push notification when a friend request is received Configuration for sending a push notification to a player when they receive a friend request from another player. Enables the recipient to respond promptly via GS2-Gateway. cancelRequestNotification NotificationSetting  Push notification when a received friend request is canceled Configuration for sending a push notification to a player when a friend request they previously received is canceled by the sender. Notifies the recipient that the pending request no longer exists. acceptRequestNotification NotificationSetting  Push notification when a friend request is approved Configuration for sending a push notification to a player when their sent friend request is accepted by the recipient. Both players are then added to each other’s friend lists. rejectRequestNotification NotificationSetting  Push notification when a friend request is rejected Configuration for sending a push notification to a player when their sent friend request is rejected by the recipient. The friend request is removed from both the send box and inbox. deleteFriendNotification NotificationSetting  Push notification when a friend is deleted Configuration for sending a push notification to a player when they are removed from another player’s friend list. The friendship is terminated for both sides. logSetting LogSetting Log Output Setting Configuration for outputting log data of friend operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for follow/unfollow, friend requests, and profile updates can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing friend operations. followScript ScriptSetting Script to run when followed Script Trigger Reference - follow unfollowScript ScriptSetting Script to run when unfollowed Script Trigger Reference - unfollow sendRequestScript ScriptSetting Script to run when a friend request is issued Script Trigger Reference - sendRequest cancelRequestScript ScriptSetting Script to execute when a friend request is canceled Script Trigger Reference - cancelRequest acceptRequestScript ScriptSetting Script to run when a friend request is accepted Script Trigger Reference - acceptRequest rejectRequestScript ScriptSetting Script to execute when a friend request is rejected Script Trigger Reference - rejectRequest deleteFriendScript ScriptSetting Script to run when a friend is deleted Script Trigger Reference - deleteFriend updateProfileScript ScriptSetting Script to run when a profile is updated Script Trigger Reference - updateProfile followNotification NotificationSetting Push notification when followed Configuration for sending a push notification to a player when another player starts following them. Allows the followed player to be notified in real time via GS2-Gateway. receiveRequestNotification NotificationSetting  Push notification when a friend request is received Configuration for sending a push notification to a player when they receive a friend request from another player. Enables the recipient to respond promptly via GS2-Gateway. cancelRequestNotification NotificationSetting  Push notification when a received friend request is canceled Configuration for sending a push notification to a player when a friend request they previously received is canceled by the sender. Notifies the recipient that the pending request no longer exists. acceptRequestNotification NotificationSetting  Push notification when a friend request is approved Configuration for sending a push notification to a player when their sent friend request is accepted by the recipient. Both players are then added to each other’s friend lists. rejectRequestNotification NotificationSetting  Push notification when a friend request is rejected Configuration for sending a push notification to a player when their sent friend request is rejected by the recipient. The friend request is removed from both the send box and inbox. deleteFriendNotification NotificationSetting  Push notification when a friend is deleted Configuration for sending a push notification to a player when they are removed from another player’s friend list. The friendship is terminated for both sides. logSetting LogSetting Log Output Setting Configuration for outputting log data of friend operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for follow/unfollow, friend requests, and profile updates can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example getProfile Get profile Retrieves the requesting user’s own profile, including all three visibility levels: public profile, follower profile, and friend profile. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Profile Profile Implementation Example getProfileByUserId Get profile by specifying a user ID Retrieves the specified user’s profile, including all three visibility levels (server-side operation). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Profile Profile Implementation Example updateProfile Update profile Updates the requesting user’s profile with three distinct visibility levels: publicProfile: visible to all users followerProfile: visible only to users who follow this user friendProfile: visible only to users who are friends with this user Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. Result Type Description item Profile Profile updated Implementation Example updateProfileByUserId Update profile by specifying a user ID Updates the specified user’s profile with three distinct visibility levels (server-side operation): publicProfile: visible to all users followerProfile: visible only to followers friendProfile: visible only to friends Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Profile Profile updated Implementation Example deleteProfileByUserId Delete profile Deletes the specified user’s profile data (server-side operation). All three visibility levels (public, follower, friend) of the profile are removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Profile Profile deleted Implementation Example describeFriends Get a list of friends Retrieves a paginated list of the requesting user’s friends. Friendship is a bidirectional relationship established when a friend request is accepted. When withProfile is set to true, each friend’s profile information (visible to friends) is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token withProfile bool false Whether to include profile information in the result 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 List of Friend nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeFriendsByUserId Get a list of friends by specifying a user ID Retrieves a paginated list of the specified user’s friends (server-side operation). When withProfile is set to true, each friend’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Friend nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeBlackList Get blacklist Retrieves a paginated list of user IDs that the requesting user has blocked. Blocked users are prevented from sending friend requests or following the user. Returns only user IDs, not full user profiles. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 Blacklisted user ID list nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeBlackListByUserId Get blacklist by specifying a user ID Retrieves a paginated list of user IDs that the specified user has blocked (server-side operation). Returns only user IDs, not full user profiles. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Blacklisted user ID list nextPageToken string Page token to retrieve the rest of the listing Implementation Example registerBlackList Add to blacklist Adds the specified target user to the requesting user’s blacklist. Once blocked, the target user will be unable to send friend requests or follow the user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item BlackList blacklist Implementation Example registerBlackListByUserId Add to blacklist by specifying a user ID Adds the specified target user to the specified user’s blacklist (server-side operation). Once blocked, the target user will be unable to send friend requests or follow the user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BlackList blacklist Implementation Example unregisterBlackList Remove a user from blacklist Removes the specified target user from the requesting user’s blacklist. After removal, the target user will be able to send friend requests and follow the user again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item BlackList Blacklist Implementation Example unregisterBlackListByUserId Remove a user from the blacklist by specifying a user ID Removes the specified target user from the specified user’s blacklist (server-side operation). After removal, the target user will be able to send friend requests and follow the user again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BlackList Blacklist Implementation Example describeFollows Get a list of followed users Retrieves a paginated list of users that the requesting user is following. When withProfile is set to true, each followed user’s profile information (visible to followers) is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token withProfile bool false Whether to include profile information in the result 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 List of users that the user follows nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeFollowsByUserId Get a list of followed users by specifying a user ID Retrieves a paginated list of users that the specified user is following (server-side operation). When withProfile is set to true, each followed user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of users that the user follows nextPageToken string Page token to retrieve the rest of the listing Implementation Example getFollow Get a followed user Retrieves information about a specific user that the requesting user is following. When withProfile is set to true, the followed user’s profile information (visible to followers) is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result Result Type Description item FollowUser Following user Implementation Example getFollowByUserId Get a followed user by specifying a user ID Retrieves information about a specific user that the specified user is following (server-side operation). When withProfile is set to true, the followed user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FollowUser Following user Implementation Example follow Follow a user Adds the specified target user to the requesting user’s follow list. Following is a one-way relationship that does not require the target user’s approval. After following, the user can view the target user’s follower-level profile information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID of the person want to follow Result Type Description item FollowUser Followed user Implementation Example followByUserId Follow a user by specifying a user ID Adds the specified target user to the specified user’s follow list (server-side operation). Following is a one-way relationship that does not require the target user’s approval. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID of the person want to follow timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FollowUser Followed user Implementation Example unfollow Unfollow a user Removes the specified target user from the requesting user’s follow list. After unfollowing, the user will no longer be able to view the target user’s follower-level profile information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item FollowUser Unfollowed user Implementation Example unfollowByUserId Unfollow a user by specifying a user ID Removes the specified target user from the specified user’s follow list (server-side operation). After unfollowing, the user will no longer be able to view the target user’s follower-level profile information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FollowUser Unfollowed user Implementation Example getFriend Get a friend Retrieves information about a specific friend of the requesting user. When withProfile is set to true, the friend’s profile information (visible to friends) is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result Result Type Description item FriendUser Friend Implementation Example getFriendByUserId Get a friend by specifying a user ID Retrieves information about a specific friend of the specified user (server-side operation). When withProfile is set to true, the friend’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendUser Friend Implementation Example addFriend Add friend Directly adds the specified target user as a friend of the requesting user, bypassing the friend request flow. This creates a one-way friend relationship. The target user’s profile is always loaded and returned after adding. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item FriendUser Added Friend Implementation Example addFriendByUserId Add friend by specifying a user ID Directly adds the specified target user as a friend of the specified user, bypassing the friend request flow (server-side operation). This creates a one-way friend relationship. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendUser Added Friend Implementation Example deleteFriend Delete friend Removes the specified target user from the requesting user’s friend list. The target user’s profile is loaded before deletion, and the deleted friend information is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item FriendUser Friend deleted Implementation Example deleteFriendByUserId Delete friend by specifying a user ID Removes the specified target user from the specified user’s friend list (server-side operation). The deleted friend information is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendUser Friend deleted Implementation Example describeSendRequests Get a list of sent friend requests Retrieves a paginated list of friend requests that the requesting user has sent and are pending a response. When withProfile is set to true, the target user’s profile information is also loaded and returned for each request. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token withProfile bool false Whether to include profile information in the result 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 List of Friend Request nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSendRequestsByUserId Get a list of sent friend requests by specifying a user ID Retrieves a paginated list of friend requests that the specified user has sent (server-side operation). When withProfile is set to true, the target user’s profile information is also loaded and returned for each request. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Friend Request nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSendRequest Get a sent friend request Retrieves a specific friend request that the requesting user has sent to the specified target user. When withProfile is set to true, the target user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result Result Type Description item FriendRequest Friend Request Implementation Example getSendRequestByUserId Get a sent friend request by specifying a user ID Retrieves a specific friend request that the specified user has sent to the specified target user (server-side operation). When withProfile is set to true, the target user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Friend Request Implementation Example sendRequest Send a friend request Sends a friend request to the specified target user. You cannot send a request to yourself. If the number of “current friends” reaches 1000, you cannot send a new request. If there is one or more “unaccepted friend requests”, the oldest “unaccepted friend request” will be withdrawn and a new request will be sent. And, if the recipient of the friend request has 1000 “unaccepted friend requests”, the oldest “unaccepted friend request” will be withdrawn and a new request will be accepted. When withProfile is set to true, the target user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID of the person want to be friend withProfile bool false Whether to include profile information in the result Result Type Description item FriendRequest Sent Friend Request Implementation Example sendRequestByUserId Send a friend request by specifying a user ID Sends a friend request to the specified target user on behalf of the specified user (server-side operation). You cannot send a request to yourself. If the number of “current friends” reaches 1000, you cannot send a new request. If there is one or more “unaccepted friend requests”, the oldest “unaccepted friend request” will be withdrawn and a new request will be sent. And, if the recipient of the friend request has 1000 “unaccepted friend requests”, the oldest “unaccepted friend request” will be withdrawn and a new request will be accepted. When withProfile is set to true, the target user’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID of the person want to be friend withProfile bool false Whether to include profile information in the result timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Sent Friend Request Implementation Example deleteRequest Cancel a sent friend request Cancels (deletes) a friend request that the requesting user has previously sent to the specified target user. The request is removed from both the sender’s sent box and the recipient’s inbox. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item FriendRequest Friend Request deleted Implementation Example deleteRequestByUserId Cancel a sent friend request by specifying a user ID Cancels (deletes) a friend request that the specified user has previously sent to the specified target user (server-side operation). The request is removed from both the sender’s sent box and the recipient’s inbox. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Friend Request deleted Implementation Example describeReceiveRequests Get a list of received friend requests Retrieves a paginated list of friend requests that have been sent to the requesting user and are pending acceptance or rejection. When withProfile is set to true, the sender’s profile information is also loaded and returned for each request. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token withProfile bool false Whether to include profile information in the result 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 List of Friend request nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeReceiveRequestsByUserId Get a list of received friend requests by specifying a user ID Retrieves a paginated list of friend requests that have been sent to the specified user (server-side operation). When withProfile is set to true, the sender’s profile information is also loaded and returned for each request. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Friend request nextPageToken string Page token to retrieve the rest of the listing Implementation Example getReceiveRequest Get a received friend request Retrieves a specific friend request sent by the specified sender to the requesting user. When withProfile is set to true, the sender’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token fromUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result Result Type Description item FriendRequest Friend request Implementation Example getReceiveRequestByUserId Get a received friend request by specifying a user ID Retrieves a specific friend request sent by the specified sender to the specified user (server-side operation). When withProfile is set to true, the sender’s profile information is also loaded and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID fromUserId string  ~ 128 chars User ID withProfile bool false Whether to include profile information in the result timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Friend request Implementation Example acceptRequest Accept friend request Accepts a pending friend request from the specified sender. Upon acceptance, a bidirectional friend relationship is established between both users, and the friend request is marked as accepted. Both users will appear in each other’s friend lists and can view each other’s friend-level profile information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token fromUserId string  ~ 128 chars User ID Result Type Description item FriendRequest Accepted Friend Request Implementation Example acceptRequestByUserId Accept friend request by specifying a user ID Accepts a pending friend request from the specified sender for the specified user (server-side operation). Upon acceptance, a bidirectional friend relationship is established between both users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID fromUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Accepted Friend Request Implementation Example rejectRequest Reject friend request Rejects a pending friend request from the specified sender. The friend request is marked as rejected and deleted. No friend relationship is established. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token fromUserId string  ~ 128 chars User ID Result Type Description item FriendRequest Rejected friend request Implementation Example rejectRequestByUserId Reject friend request by specifying a user ID Rejects a pending friend request from the specified sender for the specified user (server-side operation). The friend request is marked as rejected and deleted. No friend relationship is established. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID fromUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FriendRequest Rejected friend request Implementation Example getPublicProfile Get public profile Retrieves only the public portion of the specified user’s profile. This is the profile information that is visible to all users, regardless of follow or friend status. Unlike GetProfile, this does not require any relationship with the target user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item PublicProfile Public Profile Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Friend SDK for various programming languages\n","title":"GS2-Friend SDK API Reference","url":"/api_reference/friend/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing gateway operations. firebaseSecret string ~ 1024 chars Secret token used to send Firebase notifications The server key or secret token for Firebase Cloud Messaging (FCM). Required to enable mobile push notification forwarding when the target player is offline and cannot receive in-game WebSocket notifications. logSetting LogSetting Log Output Setting Configuration for outputting log data of gateway operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for WebSocket session management, notification delivery, and Firebase token operations can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. WebSocketSession WebSocketSession A WebSocket session is a persistent connection between a GS2 server and a client for real-time bidirectional communication. The client registers a user ID as an identifier to the server. Details  webSocketSessionId string * ~ 1024 chars WebSocket Session A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server connectionId string  ~ 128 chars Connection ID The unique identifier assigned to this WebSocket connection. Used to identify the specific client connection when sending notifications. namespaceName string  ~ 128 chars Namespace name userId string  ~ 128 chars User ID sessionId string ~ 128 chars Session ID An optional session identifier that can be associated with this WebSocket connection. Used to correlate the WebSocket session with an application-level session context. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision FirebaseToken Firebase Device Token A Firebase Device Token is required to use mobile push notifications. GS2-Gateway provides in-game push notification functionality, allowing you to receive push notifications when matchmaking is completed or missions are accomplished, but Mobile push notifications can be forwarded to a mobile push notification if the player to whom the notification is directed is offline. The Firebase Device Token is used to identify the device to be notified. As the name suggests, Firebase is an external service, so please refer to the Firebase documentation for detailed information on how to obtain the token. Details  firebaseTokenId string * ~ 1024 chars Firebase Device Token A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID token string  ~ 1024 chars Device Token for Firebase Cloud Messaging The FCM registration token obtained from the client device. Identifies the specific device to deliver mobile push notifications to when the player is offline and cannot receive in-game WebSocket notifications. The token is device-specific and may change when the app is reinstalled or data is cleared. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SendNotificationEntry Send Notification Entry Represents a notification message to be delivered to a player. The notification is first attempted via WebSocket for online players. If the player is offline and mobile push notification forwarding is enabled, the notification is forwarded to the player’s device via Firebase Cloud Messaging. Details  userId string  ~ 128 chars User ID issuer string  ~ 256 chars Notification source service The identifier of the GS2 service that originated this notification. For example, “gs2-matchmaking” for matchmaking completion notifications or “gs2-mission” for mission achievement notifications. Used by the client to determine how to handle the notification. subject string  ~ 128 chars Subject The title or summary of the notification message. When forwarded as a mobile push notification, this is displayed as the notification title on the device. payload string  ~ 1024 chars Payload The JSON data body of the notification. Contains service-specific details about the event that triggered the notification. Delivered as-is to the client via WebSocket, or included in the mobile push notification data when forwarded. enableTransferMobileNotification bool false Forwarding to mobile push notifications when the user to be notified is offline When enabled, if the target player does not have an active WebSocket connection, the notification will be forwarded to their mobile device via Firebase Cloud Messaging. Requires that the namespace has a Firebase secret configured and the player has a registered device token. sound string {enableTransferMobileNotification} == true ~ 256 chars Name of audio file to be played The name of the sound file to play when the mobile push notification is delivered. Only applicable when mobile push notification forwarding is enabled. The sound file must be included in the client application bundle. * Enabled only if enableTransferMobileNotification is true Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing gateway operations. firebaseSecret string ~ 1024 chars Secret token used to send Firebase notifications The server key or secret token for Firebase Cloud Messaging (FCM). Required to enable mobile push notification forwarding when the target player is offline and cannot receive in-game WebSocket notifications. logSetting LogSetting Log Output Setting Configuration for outputting log data of gateway operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for WebSocket session management, notification delivery, and Firebase token operations can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing gateway operations. firebaseSecret string ~ 1024 chars Secret token used to send Firebase notifications The server key or secret token for Firebase Cloud Messaging (FCM). Required to enable mobile push notification forwarding when the target player is offline and cannot receive in-game WebSocket notifications. logSetting LogSetting Log Output Setting Configuration for outputting log data of gateway operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for WebSocket session management, notification delivery, and Firebase token operations can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeWebSocketSessions Get a list of WebSocket sessions Retrieves a paginated list of active WebSocket sessions for the requesting user. Each session represents an active WebSocket connection from a client device. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of WebSocket Session nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeWebSocketSessionsByUserId Get a list of WebSocket sessions by specifying a user ID Retrieves a paginated list of active WebSocket sessions for the specified user (server-side operation). Each session represents an active WebSocket connection from a client device. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of WebSocket Session nextPageToken string Page token to retrieve the rest of the listing Implementation Example setUserId Set user ID for WebSocket session Associates the current WebSocket connection with a user ID, creating or updating the session. When allowConcurrentAccess is false, existing sessions for the same user are handled based on the force flag: If force is false and another session exists, a Conflict error is returned (prevents duplicate logins). If force is true, the existing session is disconnected and replaced. If sessionId is specified, connections with the same sessionId are allowed (useful for reconnection). When allowConcurrentAccess is true, multiple concurrent connections from the same user are allowed. Details Request  namespaceName string  ~ 128 chars Namespace name connectionId string  ~ 128 chars Connection ID The unique identifier assigned to this WebSocket connection. Used to identify the specific client connection when sending notifications. accessToken string  ~ 128 chars Access token allowConcurrentAccess bool true Whether to allow connections from different clients at the same time sessionId string {allowConcurrentAccess} == false ~ 128 chars Specifies a session ID that allows reconnection when allowConcurrentAccess is false and the existing connection has the same session ID. * Enabled only if allowConcurrentAccess is false force bool? {allowConcurrentAccess} == false false An existing WebSocket session will be disconnected before creating a new WebSocket session. * Enabled only if allowConcurrentAccess is false Result Type Description item WebSocketSession WebSocket session updated Implementation Example setUserIdByUserId Set user ID to WebSocket session by specifying a user ID Associates the current WebSocket connection with the specified user ID (server-side operation). Concurrent access control and session management behavior is the same as SetUserId. Details Request  namespaceName string  ~ 128 chars Namespace name connectionId string  ~ 128 chars Connection ID The unique identifier assigned to this WebSocket connection. Used to identify the specific client connection when sending notifications. userId string  ~ 128 chars User ID allowConcurrentAccess bool true Whether to allow connections from different clients at the same time sessionId string {allowConcurrentAccess} == false ~ 128 chars Specifies a session ID that allows reconnection when allowConcurrentAccess is false and the existing connection has the same session ID. * Enabled only if allowConcurrentAccess is false force bool? {allowConcurrentAccess} == false false An existing WebSocket session will be disconnected before creating a new WebSocket session. * Enabled only if allowConcurrentAccess is false timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item WebSocketSession WebSocket session updated Implementation Example sendNotification Send notification Sends a notification message to all active WebSocket sessions of the specified user. The notification includes a subject and payload, and optionally a sound file name. If enableTransferMobileNotification is true and the user has no active WebSocket sessions (offline), the notification may be forwarded as a mobile push notification via Firebase. Returns the protocol used and the list of connection IDs that received the notification. Details Request  namespaceName string  ~ 128 chars Namespace name userId string  ~ 128 chars User ID subject string  ~ 128 chars Subject The title or summary of the notification message. When forwarded as a mobile push notification, this is displayed as the notification title on the device. payload string  ~ 1024 chars Payload The JSON data body of the notification. Contains service-specific details about the event that triggered the notification. Delivered as-is to the client via WebSocket, or included in the mobile push notification data when forwarded. enableTransferMobileNotification bool false Forwarding to mobile push notifications when the user to be notified is offline When enabled, if the target player does not have an active WebSocket connection, the notification will be forwarded to their mobile device via Firebase Cloud Messaging. Requires that the namespace has a Firebase secret configured and the player has a registered device token. sound string {enableTransferMobileNotification} == true ~ 256 chars Name of audio file to be played The name of the sound file to play when the mobile push notification is delivered. Only applicable when mobile push notification forwarding is enabled. The sound file must be included in the client application bundle. * Enabled only if enableTransferMobileNotification is true timeOffsetToken string ~ 1024 chars Time offset token Result Type Description protocol string Protocol used for notification sendConnectionIds List List of connection IDs sent Implementation Example disconnectByUserId Disconnect WebSocket sessions by specifying a user ID Disconnects and deletes all active WebSocket sessions for the specified user. Returns the list of disconnected sessions. Details Request  namespaceName string  ~ 128 chars Namespace name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Disconnected WebSocket session Implementation Example disconnectAll Disconnect all WebSocket sessions Disconnects all WebSocket sessions in the specified namespace. This is a namespace-wide operation that affects all users’ sessions. Details Request  namespaceName string  ~ 128 chars Namespace name Result Type Description Implementation Example setFirebaseToken Set Firebase device token Registers or updates the Firebase Cloud Messaging (FCM) device token for the requesting user. If a token already exists for the user, it is updated with the new value; otherwise, a new token is created. This token is used to deliver mobile push notifications when the user is offline (no active WebSocket sessions). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token token string  ~ 1024 chars Device Token for Firebase Cloud Messaging The FCM registration token obtained from the client device. Identifies the specific device to deliver mobile push notifications to when the player is offline and cannot receive in-game WebSocket notifications. The token is device-specific and may change when the app is reinstalled or data is cleared. Result Type Description item FirebaseToken Firebase Device Token created Implementation Example setFirebaseTokenByUserId Set Firebase device token by specifying a user ID Registers or updates the Firebase Cloud Messaging (FCM) device token for the specified user (server-side operation). If a token already exists for the user, it is updated; otherwise, a new token is created. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID token string  ~ 1024 chars Device Token for Firebase Cloud Messaging The FCM registration token obtained from the client device. Identifies the specific device to deliver mobile push notifications to when the player is offline and cannot receive in-game WebSocket notifications. The token is device-specific and may change when the app is reinstalled or data is cleared. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FirebaseToken Firebase Device Token created Implementation Example getFirebaseToken Get Firebase device token Retrieves the Firebase Cloud Messaging (FCM) device token registered for the requesting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item FirebaseToken Firebase Device Token Implementation Example getFirebaseTokenByUserId Get Firebase device token by specifying a user ID Retrieves the Firebase Cloud Messaging (FCM) device token registered for the specified user (server-side operation). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FirebaseToken Firebase Device Token Implementation Example deleteFirebaseToken Delete Firebase device token Deletes the Firebase Cloud Messaging (FCM) device token registered for the requesting user. After deletion, the user will no longer receive mobile push notifications when offline. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item FirebaseToken Firebase Device Token deleted Implementation Example deleteFirebaseTokenByUserId Delete Firebase device token by specifying a user ID Deletes the Firebase Cloud Messaging (FCM) device token registered for the specified user (server-side operation). After deletion, the user will no longer receive mobile push notifications when offline. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item FirebaseToken Firebase Device Token deleted Implementation Example sendMobileNotificationByUserId Send mobile push notification Sends a mobile push notification to the specified user via Firebase Cloud Messaging (FCM). The notification includes a subject (title), payload (body), and optionally a sound file name. The user must have a registered Firebase device token for the notification to be delivered. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID subject string  ~ 256 chars Subject payload string  ~ 1024 chars Payload sound string ~ 256 chars Name of audio file to be played timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Gateway SDK for various programming languages\n","title":"GS2-Gateway SDK API Reference","url":"/api_reference/gateway/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing grade operations. Supports auto-run, atomic commit, and async processing options. changeGradeScript ScriptSetting Script setting to be executed when grade changes Script Trigger Reference - changeGrade logSetting LogSetting Log Output Setting Configuration for outputting log data of grade operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for grade changes and rank cap updates can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Status Status A status is an entity that exists for each property ID and holds the value of the current grade. The property ID is a status-specific ID and can be set to any value by the developer. It is strongly recommended that the value be the same as the property ID of the GS2-Experience. Details  statusId string * ~ 1024 chars Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision GradeModel Grade Model A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade. Details  gradeModelId string * ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Grade Model name Grade 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. gradeEntries List  1 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). DefaultGradeModel Default Grade Model You can set the default grade value according to the match of the property ID regular expression when creating a new grade. Details  propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern matched against the property ID of a newly created grade status. When the property ID matches this pattern, the specified default grade value is assigned as the initial grade instead of 0. Patterns are evaluated in order, and the first match is used. defaultGradeValue long  0 ~ 9223372036854775805 Default Grade Value The initial grade value assigned to a newly created status when its property ID matches the propertyIdRegex pattern. This value determines the starting rank cap for the linked GS2-Experience model, as the grade entry at this index defines the corresponding rank cap. GradeEntryModel Grade Entry Model Defines the mapping between a grade value and a rank cap for the linked GS2-Experience model. Each entry also specifies regex patterns for matching property IDs, enabling the system to determine which resources can be used for grade-up operations and how their property IDs are transformed. Details  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. rankCapValue long  0 ~ 9223372036854775805 Rank Cap Value The rank cap value to set in the linked GS2-Experience model when this grade is applied. When a player’s grade changes to the value corresponding to this entry, the rank cap of the associated experience status is automatically updated to this value, controlling the maximum achievable rank. propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern applied to the grade status’s property ID to extract variables for grade-up matching. Capture groups (parenthesized parts) in this pattern become available as $1, $2, etc. in gradeUpPropertyIdRegex. For example, a pattern like “character-(.+)” extracts the character identifier for use in matching grade-up material property IDs. gradeUpPropertyIdRegex string  ~ 1024 chars Grade-Up Property ID Regex A regular expression pattern that identifies which resource property IDs can be consumed for grade advancement. This pattern can reference capture groups from propertyIdRegex using $1, $2, etc. For example, if propertyIdRegex extracts “sword-001” as $1, this pattern might be “grade-up-material-$1” to match materials specific to that sword. AcquireActionRate Reward Addition Table Defines a named multiplier table that scales reward amounts based on the current grade value. Each grade value maps to a multiplier applied to acquire actions in transactions, allowing higher-graded characters or equipment to receive proportionally more rewards. Supports both standard double-precision mode and big number mode for extremely large values. Details  name string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. mode string (enum) enum {   “double”,   “big” } “double” Reward Addition Table Type Selects the numeric precision mode for multiplier values. “double” mode uses standard floating-point numbers suitable for most cases. “big” mode uses string-represented numbers supporting up to 1024 digits, for games requiring extremely large value calculations. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 1000 items Multiplier List per Grade (double mode) An array of reward multipliers indexed by grade value, using double-precision floating-point numbers. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 1000 items Multiplier List per Grade (big mode) An array of reward multipliers indexed by grade value, using string-represented numbers for extended precision. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “big” for games requiring very large number calculations. * Required if mode is “big” AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentGradeMaster Currently active Grade Model master data This master data defines the Grade Model currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Grade Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data GradeModelMaster Grade Model Master Grade Model Master is data used to edit and manage Grade Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Grade Model actually referenced by the game. An Grade Model is an entity that sets the threshold of grade required for rank advancement and for each default and maximum rank cap. Details  gradeModelId string * ~ 1024 chars Grade Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Grade Model name description string ~ 1024 chars Description 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. gradeEntries List 0 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing grade operations. Supports auto-run, atomic commit, and async processing options. changeGradeScript ScriptSetting Script setting to be executed when grade changes Script Trigger Reference - changeGrade logSetting LogSetting Log Output Setting Configuration for outputting log data of grade operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for grade changes and rank cap updates can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing grade operations. Supports auto-run, atomic commit, and async processing options. changeGradeScript ScriptSetting Script setting to be executed when grade changes Script Trigger Reference - changeGrade logSetting LogSetting Log Output Setting Configuration for outputting log data of grade operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for grade changes and rank cap updates can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeStatuses Get a list of statuses Retrieves a paginated list of grade statuses for the requesting user. Each status represents a grade value associated with a specific grade model and property ID. An optional grade model name filter can be specified to retrieve statuses for a specific grade model only. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string ~ 128 chars Grade Model name accessToken string  ~ 128 chars Access token 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStatusesByUserId Get a list of statuses by specifying a user ID Retrieves a paginated list of grade statuses for the specified user (server-side operation). Each status represents a grade value associated with a specific grade model and property ID. An optional grade model name filter can be specified to retrieve statuses for a specific grade model only. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string ~ 128 chars Grade Model name userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStatus Get Status Retrieves the grade status for the requesting user, identified by grade model name and property ID. Returns the current grade value for the specified property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. Result Type Description item Status Status Implementation Example getStatusByUserId Get status by specifying a user ID Retrieves the grade status for the specified user (server-side operation), identified by grade model name and property ID. Returns the current grade value for the specified property. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example addGradeByUserId Add grade by specifying a user ID Adds the specified grade value to the user’s current grade for the given grade model and property. After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 0 0 ~ 9223372036854775805 Gained Grade timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after addition experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example subGrade Subtract grade Subtracts the specified grade value from the requesting user’s current grade for the given grade model and property. After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 0 0 ~ 9223372036854775805 Lost Grade Result Type Description item Status Status after subtraction experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example subGradeByUserId Subtract grade by specifying a user ID Subtracts the specified grade value from the specified user’s current grade for the given grade model and property (server-side operation). After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 0 0 ~ 9223372036854775805 Lost Grade timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status after subtraction experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example setGradeByUserId Set cumulative grade gained Directly sets the grade value for the specified user’s grade status (server-side operation). The previous grade status is captured before the update and returned as the ‘old’ field for audit purposes. After setting the new grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated old Status Status before update experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example applyRankCap Apply rank cap to GS2-Experience Status Applies the rank cap corresponding to the current grade to the linked GS2-Experience status for the requesting user. Looks up the grade entry matching the current grade value to determine the rank cap value. This is useful when the grade has been modified externally and the Experience rank cap needs to be synchronized. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. Result Type Description item Status Status experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example applyRankCapByUserId Apply rank cap to GS2-Experience Status by specifying a user ID Applies the rank cap corresponding to the current grade to the linked GS2-Experience status for the specified user (server-side operation). Looks up the grade entry matching the current grade value to determine the rank cap value. This is useful when the grade has been modified externally and the Experience rank cap needs to be synchronized. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status experienceNamespaceName string GS2-Experience Namespace Name experienceStatus Status GS2-Experience Status after addition Implementation Example deleteStatusByUserId Delete status by specifying a user ID Deletes the grade status for the specified user, identified by grade model name and property ID (server-side operation). The deleted status data is returned in the response. Note that this does not automatically update the linked GS2-Experience rank cap. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status deleted Implementation Example verifyGrade Verify grade Verifies that the requesting user’s grade value satisfies a specified condition. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. If the condition is not met, an error is returned with a descriptive message including the expected and actual values. When multiplyValueSpecifyingQuantity is true, the verification threshold value is multiplied by the specified quantity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Grade is less than the specified value “lessEqual” Grade is less than or equal to the specified value “greater” Grade is greater than the specified value “greaterEqual” Grade is greater than or equal to the specified value “equal” Grade is equal to the specified value “notEqual” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Status Status deleted Implementation Example verifyGradeByUserId Verify grade by specifying a user ID Verifies that the specified user’s grade value satisfies a specified condition (server-side operation). Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. If the condition is not met, an error is returned with a descriptive message including the expected and actual values. When multiplyValueSpecifyingQuantity is true, the verification threshold value is multiplied by the specified quantity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Grade is less than the specified value “lessEqual” Grade is less than or equal to the specified value “greater” Grade is greater than the specified value “greaterEqual” Grade is greater than or equal to the specified value “equal” Grade is equal to the specified value “notEqual” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status deleted Implementation Example verifyGradeUpMaterial Verify grade up material Verifies whether a material property ID is valid for grading up the specified property. The verification builds a regex pattern from the grade entry’s PropertyIdRegex and GradeUpPropertyIdRegex, then checks if the material property ID matches. Supports two verification types: ‘match’ (material must match the pattern) and ’notMatch’ (material must not match the pattern). This is used to validate that a material item is eligible to be consumed for a grade upgrade. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “match”,   “notMatch” }  Type of verification Definition Description “match” Grade is equal to the specified value “notMatch” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. materialPropertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. Result Type Description Implementation Example verifyGradeUpMaterialByUserId Verify grade up material by specifying a user ID Verifies whether a material property ID is valid for grading up the specified property for the specified user (server-side operation). The verification builds a regex pattern from the grade entry’s PropertyIdRegex and GradeUpPropertyIdRegex, then checks if the material property ID matches. Supports two verification types: ‘match’ (material must match the pattern) and ’notMatch’ (material must not match the pattern). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “match”,   “notMatch” }  Type of verification Definition Description “match” Grade is equal to the specified value “notMatch” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. materialPropertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example multiplyAcquireActionsByUserId Multiply acquire actions by grade-based rate Multiplies the quantities of the specified acquire actions by a rate multiplier determined by the user’s current grade. The rate multiplier is looked up from the grade model’s acquireActionRates using the specified rateName and the current grade value. The multiplied acquire actions are then executed as a transaction, enabling grade-based reward scaling (e.g., higher grades receive more resources). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. rateName string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. acquireActions List [] 0 ~ 100 items List of Acquire Actions timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Rewards transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeGradeModels Get a list of Grade Models Retrieves the list of currently active (published) Grade Models in the specified namespace. Grade Models define the grade structure, including grade entries, default grades, the linked Experience Model, and acquire action rate multipliers. Unlike Grade Model Masters, these are read-only and represent the configuration currently in use. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Grade Models Implementation Example getGradeModel Get Grade Model Retrieves the detailed information of a specific currently active Grade Model by name. Includes the grade entries that define progression levels and their associated rank cap values for the linked Experience service. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model name Grade Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GradeModel Grade Model Implementation Example exportMaster Export Grade Model Master in a master data format that can be activated Exports all Grade Model Master definitions in the namespace as a single JSON document suitable for activation. The exported data includes grade models with their grade entries, default grades, experience model links, and acquire action rates. This is used to review master data before activating it, or to back up the current master configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentGradeMaster Grade Model master data that can be activated Implementation Example getCurrentGradeMaster Get currently active Grade Model master data Retrieves the Grade Model master data that is currently activated and in use in the specified namespace. The returned data contains the JSON definition of all grade models that are currently serving runtime requests. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentGradeMaster Currently active Grade Model master data Implementation Example preUpdateCurrentGradeMaster Update currently active Grade Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentGradeMaster Update currently active Grade Model master data Activates new Grade Model master data, replacing the currently active configuration. Supports two modes: ‘direct’ for inline master data (suitable for data under 1MB), and ‘preUpload’ for applying data that was previously uploaded via PreUpdate. Once activated, all grade-related runtime operations (grade lookups, rank cap applications, acquire action rate multiplications) will use the new configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentGradeMaster Updated master data of the currently active Grade Models Implementation Example updateCurrentGradeMasterFromGitHub Update currently active Grade Model master data from GitHub Checks out Grade Model master data from a specified GitHub repository and activates it. The checkout settings specify the repository, branch/tag, and file path to retrieve. This enables Git-based master data management workflows where grade configurations are version-controlled in a repository. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentGradeMaster Updated master data of the currently active Grade Models Implementation Example describeGradeModelMasters Get a list of Grade Model Masters Retrieves a paginated list of editable Grade Model Masters with optional name prefix filtering. Grade Model Masters define the grade structure including grade entries, default grades, linked Experience Model, and acquire action rates. Changes to masters do not take effect until the master data is activated via the CurrentGradeMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Grade Model name prefix 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 List of Grade Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGradeModelMaster Create a new Grade Model Master Creates a new editable Grade Model Master definition. Key configuration includes: defaultGrades: Initial grade values for new users experienceModelId: Links this grade to a GS2-Experience model for rank cap management gradeEntries: Defines each grade level with its rank cap value and property ID matching patterns acquireActionRates: Rate multipliers applied to acquire actions based on the current grade Changes do not take effect until the master data is activated via the CurrentGradeMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Grade Model name description string ~ 1024 chars Description 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeEntries List 0 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). Result Type Description item GradeModelMaster Grade Model Master created Implementation Example getGradeModelMaster Get Grade Model Master Retrieves the detailed information of a specific editable Grade Model Master by name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model name Result Type Description item GradeModelMaster Grade Model Master Implementation Example updateGradeModelMaster Update Grade Model Master Updates the description, metadata, default grades, experience model link, grade entries, and acquire action rates of an existing Grade Model Master. The grade model name cannot be changed after creation. Changes do not take effect until the master data is re-activated via the CurrentGradeMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model name description string ~ 1024 chars Description 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeEntries List 0 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). Result Type Description item GradeModelMaster Grade Model Master updated Implementation Example deleteGradeModelMaster Delete Grade Model Master Deletes an editable Grade Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gradeName string  ~ 128 chars Grade Model name Result Type Description item GradeModelMaster Grade Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Grade SDK for various programming languages\n","title":"GS2-Grade SDK API Reference","url":"/api_reference/grade/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description blockingPolicy BlockingPolicyModel  Blocking Policy The security policy configuration for this namespace that controls access to GS2 services. Defines which services are accessible, geo-restriction rules, anonymous IP detection, hosting provider IP detection, reputation-based IP filtering, and custom IP address allow/deny lists. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BlockingPolicyModel Blocking Policy Defines the comprehensive access control rules for a GS2-Guard namespace. Combines multiple security layers including service-level access control, geo-restriction by country, anonymous IP detection (Tor/proxy), hosting provider IP detection (VPN/rental servers), IP reputation filtering, and custom IP address allow/deny lists. Details  passServices List  1 ~ 100 items List of Accessible GS2 Services The list of GS2 services that clients are allowed to access through this guard namespace. Only services included in this list will be protected by the blocking policy. At least one service must be specified. defaultRestriction string (enum) enum {   “Allow”,   “Deny” } “Allow” Default Restriction The default action applied to requests that do not match any of the configured detection rules. “Allow” permits all unmatched traffic (blocklist approach), while “Deny” blocks all unmatched traffic (allowlist approach). Definition Description “Allow” Allow access that does not match the conditions “Deny” Deny access that does not match the conditions locationDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Location Detection Enables or disables geo-restriction based on the client’s country of origin. When enabled, access is filtered by country. The specific countries and the allow/deny behavior are configured via the locations and locationRestriction fields. Definition Description “Enable” Enable “Disable” Disable locations List {locationDetection} == “Enable” [] 1 ~ 100 items List of Countries to Detect Access The list of countries used for geo-restriction filtering. Each country is specified using ISO 3166-1 alpha-2 country codes. Whether these countries are allowed or denied is determined by the locationRestriction setting. Only effective when locationDetection is enabled. * Enabled only if locationDetection is “Enable” locationRestriction string (enum) enum {   “Allow”,   “Deny” } {locationDetection} == “Enable”  Location Restriction Action The action to take when a request originates from a country in the locations list. “Allow” permits access only from listed countries (allowlist), while “Deny” blocks access from listed countries (blocklist). Works in conjunction with locationDetection and the locations list. Definition Description “Allow” Allow access “Deny” Deny access * Required if locationDetection is “Enable” anonymousIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Anonymous IP Service Detection Enables or disables detection of access from anonymous IP services such as Tor exit nodes and public proxies. When enabled, requests from these sources are identified and evaluated. Definition Description “Enable” Enable “Disable” Disable anonymousIpRestriction string (enum) enum {   “Deny” } {anonymousIpDetection} == “Enable” “Deny” Anonymous IP Restriction Action The action to take when access from an anonymous IP service (Tor/public proxy) is detected. Currently only supports “Deny” to block such access. Only effective when anonymousIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if anonymousIpDetection is “Enable” hostingProviderIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Hosting Provider IP Detection Enables or disables detection of access from hosting provider IP addresses such as public VPN services and rental servers. When enabled, traffic originating from cloud infrastructure or hosting services rather than end-user devices is identified and evaluated. Definition Description “Enable” Enable “Disable” Disable hostingProviderIpRestriction string (enum) enum {   “Deny” } {hostingProviderIpDetection} == “Enable” “Deny” Hosting Provider IP Restriction Action The action to take when access from a hosting provider IP (public VPN/rental server) is detected. Currently only supports “Deny” to block such access. Only effective when hostingProviderIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if hostingProviderIpDetection is “Enable” reputationIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Reputation IP Detection Enables or disables detection of access from IP addresses with a known bad reputation. When enabled, IPs associated with bots, DDoS attacks, and other malicious activities are identified and evaluated. Definition Description “Enable” Enable “Disable” Disable reputationIpRestriction string (enum) enum {   “Deny” } {reputationIpDetection} == “Enable” “Deny” Reputation IP Restriction Action The action to take when access from an IP with a bad reputation is detected. Currently only supports “Deny” to block such access. Only effective when reputationIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if reputationIpDetection is “Enable” ipAddressesDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” IP Address Detection Enables or disables custom IP address-based access filtering. When enabled, requests are evaluated against the custom IP address list specified in the ipAddresses field. The allow/deny behavior is controlled by ipAddressRestriction. Definition Description “Enable” Enable “Disable” Disable ipAddresses List {ipAddressesDetection} == “Enable” 0 ~ 100 items List of IP Address Ranges A list of IP address ranges in CIDR notation used for custom IP-based access filtering. Each incoming request’s source IP is evaluated against these ranges. Whether matching IPs are allowed or denied is controlled by ipAddressRestriction. Only effective when ipAddressesDetection is enabled. * Enabled only if ipAddressesDetection is “Enable” ipAddressRestriction string (enum) enum {   “Allow”,   “Deny” } {ipAddressesDetection} == “Enable”  IP Address Restriction Action The action to take when a request’s source IP matches the custom IP address list. “Allow” permits access only from listed IPs (allowlist), while “Deny” blocks access from listed IPs (blocklist). Only effective when ipAddressesDetection is enabled. Definition Description “Allow” Allow access “Deny” Deny access * Required if ipAddressesDetection is “Enable” Methods describeNamespaces Get a list of Namespaces Retrieves a paginated list of GS2-Guard namespaces within the project. Each namespace defines a blocking policy that controls access restrictions such as IP address detection, anonymous IP blocking, and reputation-based IP filtering. An optional name prefix filter can be specified to narrow down the results. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new GS2-Guard namespace with the specified blocking policy. The blocking policy defines access control rules including IP address detection, anonymous IP blocking, and reputation-based IP filtering. The namespace is initially created with a “Deploying” status and transitions to “Active” once deployment is complete. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description blockingPolicy BlockingPolicyModel  Blocking Policy The security policy configuration for this namespace that controls access to GS2 services. Defines which services are accessible, geo-restriction rules, anonymous IP detection, hosting provider IP detection, reputation-based IP filtering, and custom IP address allow/deny lists. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Gets the current deployment status of the specified GS2-Guard namespace. Possible statuses include “Deploying” (initial deployment or update in progress), “Active” (deployment complete, namespace is operational), and “Deleting” (cleanup in progress). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Retrieves the detailed information of the specified GS2-Guard namespace. The returned data includes the namespace name, description, current deployment status, and the configured blocking policy with its access control rules. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the description and blocking policy of the specified GS2-Guard namespace. The namespace must be in “Active” status; updates are rejected if a deployment is currently in progress. After updating, the namespace enters “Deploying” status while the new blocking policy is applied, then returns to “Active” once complete. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description blockingPolicy BlockingPolicyModel  Blocking Policy The security policy configuration for this namespace that controls access to GS2 services. Defines which services are accessible, geo-restriction rules, anonymous IP detection, hosting provider IP detection, reputation-based IP filtering, and custom IP address allow/deny lists. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Deletes the specified GS2-Guard namespace. If a deployment is still in progress, the deletion is rejected until the deployment completes. This operation is irreversible and all data associated with the deleted namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Returns the current version of the GS2-Guard microservice. Details Request Request parameters: None Result Type Description item string Version Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Guard SDK for various programming languages\n","title":"GS2-Guard SDK API Reference","url":"/api_reference/guard/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing guild operations. Supports auto-run, atomic commit, and async processing options. changeNotification NotificationSetting Guild Change Notification Push notification sent via GS2-Gateway when guild information (display name, attributes, join policy, etc.) is updated. Allows guild members to receive real-time updates about changes to their guild. joinNotification NotificationSetting Member Join Notification Push notification sent via GS2-Gateway when a new member joins the guild, either through direct join (open policy) or after approval of a join request. Enables existing members to be notified of new additions. leaveNotification NotificationSetting Member Leave Notification Push notification sent via GS2-Gateway when a member leaves or is removed from the guild. Covers both voluntary departures and expulsions by guild masters. changeMemberNotification NotificationSetting Member Change Notification Push notification sent via GS2-Gateway when a guild member’s information (role, metadata) is updated. Whether metadata changes trigger this notification can be controlled with changeMemberNotificationIgnoreChangeMetadata. changeMemberNotificationIgnoreChangeMetadata bool? false Whether to ignore changes in metadata when issuing notifications when member metadata is updated receiveRequestNotification NotificationSetting Receive Request Notification Push notification sent via GS2-Gateway when the guild receives a new join request from a user. Allows guild masters and authorized members to be notified of pending requests that require approval. removeRequestNotification NotificationSetting Remove Request Notification Push notification sent via GS2-Gateway when a guild join request is deleted, either by cancellation from the sender, rejection by the guild, or approval (which removes the request and adds the member). createGuildScript ScriptSetting Script to execute when creating a Guild Script Trigger Reference - createGuild updateGuildScript ScriptSetting Script to execute when update a guild Script Trigger Reference - updateGuild joinGuildScript ScriptSetting Script to execute when joining a guild Script Trigger Reference - joinGuild receiveJoinRequestScript ScriptSetting Script to execute when receiving a guild join request Script Trigger Reference - receiveJoinRequest leaveGuildScript ScriptSetting Script to execute when leaving a guild Script Trigger Reference - leaveGuild changeRoleScript ScriptSetting Script to execute when changing the role assigned to a member Script Trigger Reference - changeRole deleteGuildScript ScriptSetting Script to execute when deleting a guild Script Trigger Reference - deleteGuild logSetting LogSetting Log Output Setting Configuration for outputting log data of guild operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for guild creation, joining, leaving, and role changes can be collected. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Guild 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. Details  guildId string * ~ 1024 chars Guild A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server 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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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. currentMaximumMemberCount int  1 ~ 2147483646 Current Maximum Member Count The current maximum number of members this guild can have. Initialized with the guild model’s defaultMaximumMemberCount when the guild is created, and can be increased up to maximumMemberCount through guild operations or acquire actions (e.g., guild expansion items). members List [] 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision JoinedGuild 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. Details  joinedGuildId string * ~ 1024 chars Joined Guild A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server 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 LastGuildMasterActivity 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. Details  userId string  ~ 128 chars User ID updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server ReceiveMemberRequest 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. Details  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. metadata string ~ 512 chars Metadata Optional arbitrary data attached to this join request by the applicant, such as an introduction message or application reason. Guild masters can review this data when deciding whether to approve or reject the request. Maximum 512 characters. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server SendMemberRequest 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. Details  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. metadata string ~ 512 chars Metadata Optional arbitrary data attached to this join request, such as an introduction message or application reason. This data is visible to guild masters when reviewing the request, allowing them to make informed approval decisions. Maximum 512 characters. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server IgnoreUser 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. Details  userId string  ~ 128 chars User ID createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server 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. Details  guildModelId string * ~ 1024 chars Guild Model A unique resource name assigned to all information handled by GS2\" \u003e 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  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. Details  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. Member Member An entity that manages a list of guild members Details  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 VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentGuildMaster Currently active Guild Model master data This master data defines the Guild Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Guild Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data GuildModelMaster Guild Model Master Guild Model Master is data used to edit and manage Guild Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Guild Model actually referenced by the game. A Guild Model Master 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. Details  guildModelId string * ~ 1024 chars Guild Model Master A unique resource name assigned to all information handled by GS2\" \u003e 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 (.). description string ~ 1024 chars Description metadata string ~ 1024 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  0 ~ 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  0 ~ 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  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. 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. 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. 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. 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. The value ranges from 1 to 100. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing guild operations. Supports auto-run, atomic commit, and async processing options. changeNotification NotificationSetting Guild Change Notification Push notification sent via GS2-Gateway when guild information (display name, attributes, join policy, etc.) is updated. Allows guild members to receive real-time updates about changes to their guild. joinNotification NotificationSetting Member Join Notification Push notification sent via GS2-Gateway when a new member joins the guild, either through direct join (open policy) or after approval of a join request. Enables existing members to be notified of new additions. leaveNotification NotificationSetting Member Leave Notification Push notification sent via GS2-Gateway when a member leaves or is removed from the guild. Covers both voluntary departures and expulsions by guild masters. changeMemberNotification NotificationSetting Member Change Notification Push notification sent via GS2-Gateway when a guild member’s information (role, metadata) is updated. Whether metadata changes trigger this notification can be controlled with changeMemberNotificationIgnoreChangeMetadata. changeMemberNotificationIgnoreChangeMetadata bool? false Whether to ignore changes in metadata when issuing notifications when member metadata is updated receiveRequestNotification NotificationSetting Receive Request Notification Push notification sent via GS2-Gateway when the guild receives a new join request from a user. Allows guild masters and authorized members to be notified of pending requests that require approval. removeRequestNotification NotificationSetting Remove Request Notification Push notification sent via GS2-Gateway when a guild join request is deleted, either by cancellation from the sender, rejection by the guild, or approval (which removes the request and adds the member). createGuildScript ScriptSetting Script to execute when creating a Guild Script Trigger Reference - createGuild updateGuildScript ScriptSetting Script to execute when update a guild Script Trigger Reference - updateGuild joinGuildScript ScriptSetting Script to execute when joining a guild Script Trigger Reference - joinGuild receiveJoinRequestScript ScriptSetting Script to execute when receiving a guild join request Script Trigger Reference - receiveJoinRequest leaveGuildScript ScriptSetting Script to execute when leaving a guild Script Trigger Reference - leaveGuild changeRoleScript ScriptSetting Script to execute when changing the role assigned to a member Script Trigger Reference - changeRole deleteGuildScript ScriptSetting Script to execute when deleting a guild Script Trigger Reference - deleteGuild logSetting LogSetting Log Output Setting Configuration for outputting log data of guild operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for guild creation, joining, leaving, and role changes can be collected. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing guild operations. Supports auto-run, atomic commit, and async processing options. changeNotification NotificationSetting Guild Change Notification Push notification sent via GS2-Gateway when guild information (display name, attributes, join policy, etc.) is updated. Allows guild members to receive real-time updates about changes to their guild. joinNotification NotificationSetting Member Join Notification Push notification sent via GS2-Gateway when a new member joins the guild, either through direct join (open policy) or after approval of a join request. Enables existing members to be notified of new additions. leaveNotification NotificationSetting Member Leave Notification Push notification sent via GS2-Gateway when a member leaves or is removed from the guild. Covers both voluntary departures and expulsions by guild masters. changeMemberNotification NotificationSetting Member Change Notification Push notification sent via GS2-Gateway when a guild member’s information (role, metadata) is updated. Whether metadata changes trigger this notification can be controlled with changeMemberNotificationIgnoreChangeMetadata. changeMemberNotificationIgnoreChangeMetadata bool? false Whether to ignore changes in metadata when issuing notifications when member metadata is updated receiveRequestNotification NotificationSetting Receive Request Notification Push notification sent via GS2-Gateway when the guild receives a new join request from a user. Allows guild masters and authorized members to be notified of pending requests that require approval. removeRequestNotification NotificationSetting Remove Request Notification Push notification sent via GS2-Gateway when a guild join request is deleted, either by cancellation from the sender, rejection by the guild, or approval (which removes the request and adds the member). createGuildScript ScriptSetting Script to execute when creating a Guild Script Trigger Reference - createGuild updateGuildScript ScriptSetting Script to execute when update a guild Script Trigger Reference - updateGuild joinGuildScript ScriptSetting Script to execute when joining a guild Script Trigger Reference - joinGuild receiveJoinRequestScript ScriptSetting Script to execute when receiving a guild join request Script Trigger Reference - receiveJoinRequest leaveGuildScript ScriptSetting Script to execute when leaving a guild Script Trigger Reference - leaveGuild changeRoleScript ScriptSetting Script to execute when changing the role assigned to a member Script Trigger Reference - changeRole deleteGuildScript ScriptSetting Script to execute when deleting a guild Script Trigger Reference - deleteGuild logSetting LogSetting Log Output Setting Configuration for outputting log data of guild operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for guild creation, joining, leaving, and role changes can be collected. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example searchGuilds Search Guilds Searches for guilds with various filter criteria. Supports filtering by displayName (partial match), integer attributes (attributes1-5), and join policies. Results can be sorted by number of players, attribute values (ascending/descending), or last updated time. By default, guilds at full member capacity are excluded; set includeFullMembersGuild to true to include them. Details Request  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 Access token displayName string ~ 64 chars Display name to search for guild attributes1 List 0 ~ 10 items List of guild operation policies to search for guild attributes2 List 0 ~ 10 items List of guild operation policies to search for guild attributes3 List 0 ~ 10 items List of guild operation policies to search for guild attributes4 List 0 ~ 10 items List of guild operation policies to search for guild attributes5 List 0 ~ 10 items List of guild operation policies to search for guild joinPolicies List 0 ~ 10 items List of guild join policies to search for guild includeFullMembersGuild bool? false Whether to include full guilds in search results orderBy string (enum) enum {   “number_of_players”,   “attribute1_asc”,   “attribute1_desc”,   “attribute2_asc”,   “attribute2_desc”,   “attribute3_asc”,   “attribute3_desc”,   “attribute4_asc”,   “attribute4_desc”,   “attribute5_asc”,   “attribute5_desc”,   “last_updated” } “number_of_players” Sort order Definition Description “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 List of Guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example searchGuildsByUserId Search Guilds by specifying a user ID Searches for guilds with various filter criteria (server-side operation). The same filtering, sorting, and full-member-guild exclusion options apply as in the user-facing version. Details Request  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 (.). userId string  ~ 128 chars User ID displayName string ~ 64 chars Display name to search for guild attributes1 List 0 ~ 10 items List of guild operation policies to search for guild attributes2 List 0 ~ 10 items List of guild operation policies to search for guild attributes3 List 0 ~ 10 items List of guild operation policies to search for guild attributes4 List 0 ~ 10 items List of guild operation policies to search for guild attributes5 List 0 ~ 10 items List of guild operation policies to search for guild joinPolicies List 0 ~ 10 items List of guild join policies to search for guild includeFullMembersGuild bool? false Whether to include full guilds in search results orderBy string (enum) enum {   “number_of_players”,   “attribute1_asc”,   “attribute1_desc”,   “attribute2_asc”,   “attribute2_desc”,   “attribute3_asc”,   “attribute3_desc”,   “attribute4_asc”,   “attribute4_desc”,   “attribute5_asc”,   “attribute5_desc”,   “last_updated” } “number_of_players” Sort order Definition Description “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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGuild Create a new Guild Creates a new guild and automatically registers the requesting user as the guild master. Validates that the user’s maxConcurrentJoinGuilds limit is not exceeded before creation. The guild can be configured with a display name, custom attributes (attribute1-5), join policy, custom roles, and default member role. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token guildModelName string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). 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 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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 Guild Guild created Implementation Example createGuildByUserId Create a new Guild by specifying a user ID Creates a new guild with the specified user as the guild master (server-side operation). The same maxConcurrentJoinGuilds validation applies as in the user-facing version. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID guildModelName string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). 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 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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Guild Guild created Implementation Example getGuild Get Guild Retrieves the detailed information of a specific guild, including its members, custom attributes, join policy, and roles. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 Guild Guild Implementation Example getGuildByUserId Get Guild by specifying a user ID Retrieves the detailed information of a specific guild (server-side operation), including its members, custom attributes, join policy, and roles. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Guild Guild Implementation Example updateGuild Update Guild Updates the guild’s configuration including display name, custom attributes (attribute1-5), metadata, join policy, custom roles, and default member role. Executes the UpdateGuildScript callback with both the old and new guild data. Sends a change notification to all guild members informing them of the update. Please specify the access token of the guild user to Assume. Details Request  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 (.). 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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 Guild Guild updated Implementation Example updateGuildByGuildName Update Guild by specifying a Guild name Updates the specified guild’s configuration (server-side operation). The same UpdateGuildScript callback and member change notification apply as in the guild-user-facing version. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). guildName string  ~ 128 chars Guild name guildModelName string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). 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. Definition Description “anybody” Anybody can join “approval” Approval required customRoles List [] 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 Guild Guild updated Implementation Example deleteMember Expel member Removes the specified user from the guild’s member list. Before removal, validates that the guild will still have at least one guild master after the expulsion; if the target user is the last guild master, the operation is rejected with a GuildMasterRequired error. Please specify the access token as the access token assumed by the guild user. Details Request  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 Guild Guild updated Implementation Example deleteMemberByGuildName Expel member by specifying a Guild name Removes the specified user from the specified guild’s member list (server-side operation). The same guild master count validation (GuildMasterRequired) applies as in the guild-user-facing version. Details Request  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  ~ 128 chars Guild name targetUserId string  ~ 128 chars User ID to be expelled Result Type Description item Guild Guild updated Implementation Example updateMemberRole Update member role Changes the role of a specific guild member to the specified role name. Validates that the target user is a member of the guild before updating. The member’s role update timestamp is also refreshed. Please specify the access token as the access token assumed by the guild user. Details Request  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 Guild Guild updated Implementation Example updateMemberRoleByGuildName Update member role by specifying a Guild name Changes the role of a specific guild member in the specified guild (server-side operation). The same member validation and timestamp update apply as in the guild-user-facing version. Details Request  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  ~ 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 Guild Guild updated Implementation Example batchUpdateMemberRole Update member role in bulk Updates the roles of multiple guild members in a single operation. Only the members specified in the request are updated; members not included in the list retain their current roles. Please specify the access token as the access token assumed by the guild user. Details Request  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  1 ~ 100 items List of members to update Result Type Description item Guild Guild updated Implementation Example batchUpdateMemberRoleByGuildName Update member role in bulk by specifying a Guild name Updates the roles of multiple guild members in the specified guild in a single operation (server-side operation). Only the members specified in the request are updated; members not included retain their current roles. Details Request  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  ~ 128 chars Guild name members List  1 ~ 100 items List of members to update Result Type Description item Guild Guild updated Implementation Example deleteGuild Delete Guild Deletes the guild and all associated data. All guild members are removed, with each member’s LeaveGuildScript callback executed and LeaveNotification sent. Details Request  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 Guild Guild deleted Implementation Example deleteGuildByGuildName Delete Guild by specifying a Guild name Deletes the specified guild and all associated data (server-side operation). The same LeaveGuildScript callbacks and LeaveNotifications apply as in the guild-user-facing version. Details Request  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  ~ 128 chars Guild name Result Type Description item Guild Guild deleted Implementation Example increaseMaximumCurrentMaximumMemberCountByGuildName Add the maximum number of members by specifying a Guild name Increases the guild’s currentMaximumMemberCount by the specified value. The resulting value must not exceed the maximumMemberCount defined in the guild model. Details Request  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  ~ 128 chars Guild name value int 1 ~ 2147483646 Increase the maximum number of members Result Type Description item Guild Guild updated Implementation Example decreaseMaximumCurrentMaximumMemberCount Decrease the maximum number of members Decreases the guild’s currentMaximumMemberCount by the specified value. The resulting value cannot go below zero. Details Request  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 value int 1 ~ 2147483646 Increase the maximum number of members Result Type Description item Guild Guild updated Implementation Example decreaseMaximumCurrentMaximumMemberCountByGuildName Decrease the maximum number of members by specifying a Guild name Decreases the specified guild’s currentMaximumMemberCount by the specified value (server-side operation). The resulting value cannot go below zero. Details Request  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  ~ 128 chars Guild name value int 1 ~ 2147483646 Increase the maximum number of members Result Type Description item Guild Guild updated Implementation Example verifyCurrentMaximumMemberCount Verify the maximum number of guild members Verifies the guild’s currentMaximumMemberCount against the specified value using the chosen comparison operator. Supported operators: less, lessEqual, greater, greaterEqual, equal, notEqual. If the verification fails, an error is returned. This is useful for conditional logic in transactions. Details Request  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 verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” The maximum number of guild members is less than the specified value “lessEqual” The maximum number of guild members is less than or equal to the specified value “greater” The maximum number of guild members is greater than the specified value “greaterEqual” The maximum number of guild members is greater than or equal to the specified value “equal” The maximum number of guild members is equal to the specified value “notEqual” The maximum number of guild members is not equal to the specified value value int 1 ~ 2147483646 Maximum number of guild members multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Guild Guild updated Implementation Example verifyCurrentMaximumMemberCountByGuildName Verify the maximum number of guild members by specifying a Guild name Verifies the specified guild’s currentMaximumMemberCount against the specified value using the chosen comparison operator (server-side operation). Supported operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Details Request  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  ~ 128 chars Guild name verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” The maximum number of guild members is less than the specified value “lessEqual” The maximum number of guild members is less than or equal to the specified value “greater” The maximum number of guild members is greater than the specified value “greaterEqual” The maximum number of guild members is greater than or equal to the specified value “equal” The maximum number of guild members is equal to the specified value “notEqual” The maximum number of guild members is not equal to the specified value value int 1 ~ 2147483646 Maximum number of guild members multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Guild Guild updated Implementation Example verifyIncludeMember Verify if guild members include user ID Verifies whether the specified user is or is not a member of the guild. Supports two verification types: ‘include’ checks that the user is a guild member, ’notInclude’ checks that the user is not a guild member. If the verification fails, an error is returned. Details Request  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. accessToken string  ~ 128 chars Access token verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Guild members include the specified user “notInclude” Guild members do not include the specified user Result Type Description item Guild Guild updated Implementation Example verifyIncludeMemberByUserId Verify if guild members include user ID by specifying a user ID Verifies whether the specified user is or is not a member of the guild (server-side operation). Supports two verification types: ‘include’ and ’notInclude’. Details Request  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. userId string  ~ 128 chars User ID verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Guild members include the specified user “notInclude” Guild members do not include the specified user timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Guild Guild updated Implementation Example setMaximumCurrentMaximumMemberCountByGuildName Set the maximum number of guild members by specifying a Guild name Sets the guild’s currentMaximumMemberCount to the specified absolute value. Unlike increase/decrease operations, this directly sets the value rather than applying a delta. Returns both the updated guild and the guild state before the update, allowing the caller to track the change. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). guildName string  ~ 128 chars Guild name guildModelName string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). value int 1 ~ 2147483646 Set the maximum number of members Result Type Description item Guild Guild updated old Guild Guild before update Implementation Example assume Get an access token to act as a guild user Issues an access token that allows the requesting user to perform operations as the guild entity. This token is required for guild management operations such as updating guild settings, managing members, accepting/rejecting join requests, and managing the ignore list. The requesting user must be a member of the guild; otherwise, a NotIncludedGuildMember error is returned. The response includes the access token, the guild’s user ID, and the token’s expiration timestamp. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 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 Implementation Example assumeByUserId Get an access token to act as a guild user by specifying the user ID Issues an access token that allows the specified user to perform operations as the guild entity (server-side operation). The specified user must be a member of the guild; otherwise, a NotIncludedGuildMember error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token 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 Implementation Example describeJoinedGuilds Get a list of joined Guilds Retrieves a paginated list of guilds that the requesting user is currently a member of. An optional guild model name filter can be specified to retrieve joined guilds for a specific guild model only. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 Joining guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeJoinedGuildsByUserId Get a list of joined Guilds by specifying a user ID Retrieves a paginated list of guilds that the specified user is currently a member of (server-side operation). An optional guild model name filter can be specified to retrieve joined guilds for a specific guild model only. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Joining guild nextPageToken string Page token to retrieve the rest of the listing Implementation Example getJoinedGuild Get Joining Guild Retrieves the membership information for a specific guild that the requesting user has joined, identified by guild model name and guild name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 JoinedGuild Joining guild Implementation Example getJoinedGuildByUserId Get Joining Guild by specifying a user ID Retrieves the membership information for a specific guild that the specified user has joined (server-side operation). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item JoinedGuild Joining guild Implementation Example updateMemberMetadata Update member metadata Updates the metadata of the requesting user’s membership within the specified guild. Details Request  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. accessToken string  ~ 128 chars Access token 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 Guild Guild updated Implementation Example updateMemberMetadataByUserId Update member metadata by specifying a user ID Updates the metadata of the specified user’s membership within the specified guild (server-side operation). Details Request  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. userId string  ~ 128 chars User ID to be updated 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Guild Guild updated Implementation Example withdrawal Withdrawal from the Guild The requesting user leaves the specified guild. If a rejoin cooldown (rejoinCoolTimeMinutes) is configured in the guild model, the user cannot rejoin the same guild until the cooldown period has elapsed. If the user is the only guild master, the withdrawal is rejected with a GuildMasterRequired error to prevent leaving the guild without a leader. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 JoinedGuild Guild that withdrew guild Guild Guild Implementation Example withdrawalByUserId Withdrawal from the Guild by specifying the user ID The specified user leaves the specified guild (server-side operation). The same rejoin cooldown and guild master validation apply as in the user-facing version. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item JoinedGuild Guild that withdrew guild Guild Guild Implementation Example getLastGuildMasterActivity Get last activity date and time of guild master Retrieves the timestamp of the last activity performed by the guild master. This information is used to determine whether the guild master has been inactive long enough for automatic succession via PromoteSeniorMember. The inactivity threshold is calculated based on the inactivityPeriodDays setting in the guild model. Details Request  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 LastGuildMasterActivity User ID that refuse to participate guild Guild Guild Implementation Example getLastGuildMasterActivityByGuildName Get last activity date and time of guild master by specifying a Guild name Retrieves the timestamp of the last activity performed by the guild master for the specified guild (server-side operation). This information is used to determine whether the guild master has been inactive long enough for automatic succession. Details Request  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  ~ 128 chars Guild name Result Type Description item LastGuildMasterActivity User ID that refuse to participate guild Guild Guild Implementation Example promoteSeniorMember Promote the most senior guild member to guild master if the guild master has not logged in for a certain period of time Checks whether the guild master has been inactive longer than the inactivityPeriodDays threshold (calculated as 24 hours x inactivityPeriodDays). If the condition is met, the longest-serving non-master member (determined by JoinedAt timestamp) is promoted to the guild master role. When maxConcurrentGuildMasterCount is 1, the inactive guild master is demoted to the default member role before the promotion occurs. Details Request  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 LastGuildMasterActivity User ID that refuse to participate guild Guild Guild Implementation Example promoteSeniorMemberByGuildName Replace an inactive guild master with the longest-serving member by guild name Checks whether the guild master of the specified guild has been inactive longer than the inactivityPeriodDays threshold (server-side operation). If the condition is met, the longest-serving non-master member (determined by JoinedAt timestamp) is promoted to the guild master role. When maxConcurrentGuildMasterCount is 1, the inactive guild master is demoted to the default member role before the promotion occurs. Details Request  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  ~ 128 chars Guild name Result Type Description item LastGuildMasterActivity User ID that refuse to participate guild Guild Guild Implementation Example describeReceiveRequests Get a list of Received Join Requests Retrieves a paginated list of join requests that have been sent to the guild and are awaiting approval. Requires the access token of the assumed guild user. Details Request  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 List of join request nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeReceiveRequestsByGuildName Get a list of Received Join Requests by specifying a Guild name Retrieves a paginated list of join requests that have been sent to the specified guild and are awaiting approval (server-side operation). Details Request  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  ~ 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 List of join request nextPageToken string Page token to retrieve the rest of the listing Implementation Example getReceiveRequest Get Received Join Request Retrieves a specific join request received by the guild from the specified user. Details Request  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 fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Join request Implementation Example getReceiveRequestByGuildName Get Received Join Request by specifying a Guild name Retrieves a specific join request received by the specified guild from the specified user (server-side operation). Details Request  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  ~ 128 chars Guild name fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Join request Implementation Example acceptRequest Accept join request Accepts a pending join request, adding the requesting user as a guild member. The user is assigned the guild’s default member role, and their member metadata from the original request is preserved. The request is removed from both the guild’s inbox and the sender’s send box. Validates that the user’s maxConcurrentJoinGuilds limit is not exceeded and the guild’s maximum member count is not reached. Details Request  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 fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Accepted join request guild Guild Guild Implementation Example acceptRequestByGuildName Accept join request by specifying a Guild name Accepts a pending join request for the specified guild (server-side operation), adding the requesting user as a guild member. The same member assignment, metadata preservation, and limit validations apply as in the guild-user-facing version. Details Request  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  ~ 128 chars Guild name fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Accepted join request guild Guild Guild Implementation Example rejectRequest Reject join request Rejects a pending join request, removing it from both the guild’s inbox and the sender’s send box. The requesting user is not added to the guild. No relationship is established. Details Request  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 fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Rejected join request Implementation Example rejectRequestByGuildName Reject join request by specifying a Guild name Rejects a pending join request for the specified guild (server-side operation). The request is removed from both the guild’s inbox and the sender’s send box. Details Request  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  ~ 128 chars Guild name fromUserId string  ~ 128 chars User ID Result Type Description item ReceiveMemberRequest Rejected join request Implementation Example describeSendRequests Get a list of Sent Join Requests Retrieves a paginated list of guild join requests that the requesting user has sent and are pending a response. Results can be filtered by guild model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of join requests nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSendRequestsByUserId Get a list of Sent Join Requests by specifying a user ID Retrieves a paginated list of guild join requests that the specified user has sent (server-side operation). Results can be filtered by guild model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of join requests nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSendRequest Get Sent Join Request Retrieves a specific guild join request that the requesting user has sent to the specified target guild. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 SendMemberRequest Join Request Implementation Example getSendRequestByUserId Get Sent Join Request by specifying a user ID Retrieves a specific guild join request that the specified user has sent to the specified target guild (server-side operation). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SendMemberRequest Join Request Implementation Example sendRequest Send a join request Sends a join request to the specified guild. The behavior depends on the guild’s join policy: “anybody” policy: The user is immediately added to the guild as a member with the default role, without requiring approval. Approval-required policy: A join request is created in both the sender’s send box and the guild’s inbox, awaiting guild master approval. Before sending, the following validations are performed: the user is not on the guild’s ignore list, the rejoin cooldown period has elapsed (if the user previously left), and the maxConcurrentJoinGuilds limit is not exceeded. Custom member metadata can be included with the request. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 Guild Joined guild Responds when a join request is made to a guild that does not require approval sendMemberRequest SendMemberRequest Sent Join Request Responds when a join request is made to a guild that requires approval Implementation Example sendRequestByUserId Send a join request by specifying the user ID Sends a join request to the specified guild on behalf of the specified user (server-side operation). The same join policy behavior, validations (ignore list, cooldown, concurrent guild limit), and approval flow apply as in the user-facing version. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Guild Joined guild Responds when a join request is made to a guild that does not require approval sendMemberRequest SendMemberRequest Sent Join Request Responds when a join request is made to a guild that requires approval Implementation Example deleteRequest Cancel a sent join request Cancels (deletes) a guild join request that the requesting user has previously sent. The request is removed from both the sender’s send box and the target guild’s inbox. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 SendMemberRequest Join request deleted Implementation Example deleteRequestByUserId Cancel a sent join request by specifying a user ID Cancels (deletes) a guild join request that the specified user has previously sent (server-side operation). The request is removed from both the sender’s send box and the target guild’s inbox. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SendMemberRequest Join request deleted Implementation Example describeIgnoreUsers Get a list of User IDs that refuse to participate Retrieves a paginated list of users on the guild’s ignore list (blacklist). Users on this list are prevented from sending join requests to the guild. Requires the access token of the assumed guild user. Details Request  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 List of User IDs that refuse to participate nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeIgnoreUsersByGuildName Get a list of User IDs that refuse to participate by specifying a Guild name Retrieves a paginated list of users on the specified guild’s ignore list (blacklist) (server-side operation). Users on this list are prevented from sending join requests to the guild. Details Request  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  ~ 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 List of User IDs that refuse to participate nextPageToken string Page token to retrieve the rest of the listing Implementation Example getIgnoreUser Get User ID that refuse to participate Checks whether a specific user is on the guild’s ignore list (blacklist). Details Request  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 IgnoreUser User ID that refuse to participate Implementation Example getIgnoreUserByGuildName Get User ID that refuse to participate by specifying a Guild name Checks whether a specific user is on the specified guild’s ignore list (blacklist) (server-side operation). Details Request  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  ~ 128 chars Guild name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item IgnoreUser User ID that refuse to participate Implementation Example addIgnoreUser Add User ID that refuse to participate Adds a user to the guild’s ignore list (blacklist). Once added, the user will be unable to send join requests to this guild. If the user already has a pending join request, it is not automatically removed; it must be rejected separately. Details Request  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 IgnoreUser User ID that refuse to participate guild Guild Guild Implementation Example addIgnoreUserByGuildName Add User ID that refuse to participate by specifying a Guild name Adds a user to the specified guild’s ignore list (blacklist) (server-side operation). Once added, the user will be unable to send join requests to this guild. Details Request  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  ~ 128 chars Guild name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item IgnoreUser User ID that refuse to participate guild Guild Guild Implementation Example deleteIgnoreUser Delete User ID that refuse to participate Removes a user from the guild’s ignore list (blacklist). After removal, the user will be able to send join requests to this guild again. Details Request  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 IgnoreUser User ID that refuse to participate Implementation Example deleteIgnoreUserByGuildName Delete User ID that refuse to participate by specifying a Guild name Removes a user from the specified guild’s ignore list (blacklist) (server-side operation). After removal, the user will be able to send join requests to this guild again. Details Request  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  ~ 128 chars Guild name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item IgnoreUser User ID that refuse to participate Implementation Example describeGuildModels Get a list of Guild Models Retrieves the list of currently active (published) Guild Models in the specified namespace. Guild Models define the guild structure including maximum member count, role definitions, guild master role, default member role, join cooldown period, concurrent guild join limits, and inactive guild master succession settings. Unlike Guild Model Masters, these are read-only and represent the configuration currently in use. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Guild Model Implementation Example getGuildModel Get Guild Model Retrieves the detailed information of a specific currently active Guild Model by name. Includes role definitions, maximum member count settings, join policy constraints, inactive guild master succession period (inactivityPeriodDays), and rejoin cooldown configuration. Details Request  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 GuildModel Guild Model Implementation Example exportMaster Export Guild Model Master in a master data format that can be activated Exports all Guild Model Master definitions in the namespace as a single JSON document suitable for activation. The exported data includes guild models with their member limits, role definitions, join policies, and succession settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentGuildMaster Guild Model master data that can be activated Implementation Example getCurrentGuildMaster Get currently active Guild Model master data Retrieves the Guild Model master data that is currently activated and in use in the specified namespace. The returned data contains the JSON definition of all guild models that are currently serving runtime requests. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentGuildMaster Currently active Guild Model master data Implementation Example preUpdateCurrentGuildMaster Update Currently Active Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentGuildMaster Update currently active Guild Model master data Activates new Guild Model master data, replacing the currently active configuration. Supports two modes: ‘direct’ for inline master data (suitable for data under 1MB), and ‘preUpload’ for applying data that was previously uploaded via PreUpdate. Once activated, all guild-related runtime operations (guild creation, join requests, member management) will use the new configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentGuildMaster Updated master data of the currently active Guild Models Implementation Example updateCurrentGuildMasterFromGitHub Update the currently active guild settings from GitHub Checks out Guild Model master data from a specified GitHub repository and activates it. The checkout settings specify the repository, branch/tag, and file path to retrieve. This enables Git-based master data management workflows where guild configurations are version-controlled in a repository. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentGuildMaster Updated master data of the currently active Guild Models Implementation Example describeGuildModelMasters Get a list of Guild Model Masters Retrieves a paginated list of editable Guild Model Master definitions with optional name prefix filtering. Changes to masters do not take effect until the master data is activated via the CurrentGuildMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Guild Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGuildModelMaster Create a new Guild Model Master Creates a new editable Guild Model Master definition. Key configuration includes: defaultMaximumMemberCount / maximumMemberCount: Initial and upper limit for guild member capacity roles: Role definitions available within guilds of this model guildMasterRole / guildMemberDefaultRole: Role assigned to the creator and new members respectively inactivityPeriodDays: Number of days of inactivity before guild master auto-succession is triggered rejoinCoolTimeMinutes: Cooldown period after leaving before a user can rejoin the same guild maxConcurrentJoinGuilds: Maximum number of guilds a user can join simultaneously maxConcurrentGuildMasterCount: Maximum number of guild masters allowed per guild Changes do not take effect until the master data is activated via the CurrentGuildMaster API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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  0 ~ 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  0 ~ 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  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. 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. 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. 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. 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. The value ranges from 1 to 100. Result Type Description item GuildModelMaster Guild Model Master created Implementation Example getGuildModelMaster Get Guild Model Master Retrieves the detailed information of a specific editable Guild Model Master by name. Details Request  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 GuildModelMaster Guild Model Master Implementation Example updateGuildModelMaster Update Guild Model Master Updates the configuration of an existing Guild Model Master. All properties except the name can be changed, including member limits, roles, join cooldown, and inactivity succession settings. Changes do not take effect until the master data is re-activated via the CurrentGuildMaster API. Details Request  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 (.). description string ~ 1024 chars Description metadata string ~ 1024 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  0 ~ 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  0 ~ 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  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. 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. 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. 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. 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. The value ranges from 1 to 100. Result Type Description item GuildModelMaster Guild Model Master updated Implementation Example deleteGuildModelMaster Delete Guild Model Master Deletes an editable Guild Model Master definition. This only affects the master data; the currently active (published) model is not affected until the master data is re-activated. Details Request  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 GuildModelMaster Guild Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Guild SDK for various programming languages\n","title":"GS2-Guild SDK API Reference","url":"/api_reference/guild/sdk/"},{"content":"Models Identifier Credential Credentials used to access the GS2 API. A credential consists of a client ID and a client secret, and access using the credential is restricted based on the privileges of the user who owns the credential. Details  clientId string  UUID ~ 256 chars Client ID userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this credential. The credential inherits the permissions of this user based on the security policies attached to them. clientSecret string  UUID ~ 100 chars Client Secret createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Password Password Password for logging into the Management Console based on user permissions. A password allows different accounts to log in to a single project and still limit the information they have access to. Details  passwordId string * ~ 1024 chars Password A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. enableTwoFactorAuthentication string (enum) enum {   “RFC6238”,   “Disable” } “Disable” Two-Factor Authentication Controls whether TOTP-based two-factor authentication (RFC 6238) is required for management console login with this password. When set to “RFC6238”, the user must provide a valid one-time code from their authenticator app in addition to the password. When set to “Disable”, only the password is required. Definition Description “RFC6238” Enable “Disable” Disable twoFactorAuthenticationSetting TwoFactorAuthenticationSetting {enableTwoFactorAuthentication} == “RFC6238” Two-Factor Authentication Setting The TOTP configuration for this password, including the shared secret key and setup status. Only present when enableTwoFactorAuthentication is set to “RFC6238”. Contains the verification state (Verifying/Enable) to track whether the user has completed the authenticator app setup. * Enabled only if enableTwoFactorAuthentication is “RFC6238” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision AttachSecurityPolicy Attached Security Policy Manages the association between a GS2-Identifier user and their security policies. Each user has one attachment record that contains the list of security policy GRNs applied to that user. When the user’s credentials are used for API access, all attached policies are evaluated to determine whether the requested operation is allowed or denied. Details  userId string * ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server securityPolicyIds List [] 0 ~ 100 items List of Security Policy GRNs The list of security policies attached to this user. Multiple policies can be attached, and their permissions are combined (union). If any attached policy allows an action, the action is permitted. Up to 100 policies can be attached per user. attachedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision User GS2-Identifier User This entity represents a game developer who has access to the project. The user has credentials for programmatic access and A password can be registered that allows the user to log into the Management Console and manage the project based on the user’s permissions. Details  userId string * ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SecurityPolicy Security Policy Define restrictions on the types of APIs that users can use and the resources they can access. Access restriction rules are defined using JSON format definition data called policy documents. For the specifications of policy documents, please refer to the explanation page on policy documents in the development documents. Details  securityPolicyId string * ~ 1024 chars Security Policy A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description policy string  ~ 524288 chars Policy Document A JSON document that defines the access control rules for this security policy. The document specifies which GS2 API actions are allowed or denied, and which resources (identified by GRN patterns) the rules apply to. Multiple statements can be combined to create fine-grained access control. Maximum 512KB. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server ProjectToken Project Token A temporary access token issued by authenticating with a credential (client ID and client secret). This token is used to authorize all subsequent GS2 API calls within the project. The token has a limited lifetime and must be refreshed periodically. Details  token string ~ 1024 chars Project Token The token string used for API authentication. This token is generated upon successful login with a credential. Maximum 1024 characters. TwoFactorAuthenticationSetting Two-Factor Authentication Setting Configuration for TOTP-based two-factor authentication (RFC 6238) on a management console password. Stores the shared secret key used to generate and verify time-based one-time passwords. The setting goes through a verification phase before being fully enabled to ensure the user has correctly configured their authenticator app. Details  status string (enum) enum {   “Verifying”,   “Enable” } “Verifying” Status The current state of the two-factor authentication setup. “Verifying” indicates the user has initiated setup but has not yet confirmed a valid TOTP code from their authenticator app. “Enable” indicates the setup is complete and two-factor authentication is actively enforced for console logins. Definition Description “Verifying” Verifying “Enable” Enable Methods describeIdentifiers Get a list of Credentials Retrieves a paginated list of OAuth credentials (client ID/secret pairs) associated with the specified user. Credentials are used for programmatic authentication via the Login API to obtain project tokens. Details Request  userName string  ~ 128 chars User name pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Credentials nextPageToken string Page token to retrieve the rest of the listing Implementation Example createIdentifier Create a new Credential Generates a new OAuth credential (client ID and client secret) for the specified user. The client secret is returned only in this response and cannot be retrieved later; store it securely. The credential can be used with the Login API to obtain project tokens for programmatic API access. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this credential. The credential inherits the permissions of this user based on the security policies attached to them. Result Type Description item Identifier Created Credential clientSecret string Client Secret Implementation Example getIdentifier Get Credentials Retrieves the metadata of a specific credential identified by client ID. The client secret is not included in the response for security reasons. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this credential. The credential inherits the permissions of this user based on the security policies attached to them. clientId string  UUID ~ 256 chars Client ID Result Type Description item Identifier Credential Implementation Example deleteIdentifier Delete credential Revokes and deletes the specified credential. After deletion, the client ID and client secret can no longer be used for authentication. Any existing project tokens obtained with this credential remain valid until they expire. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this credential. The credential inherits the permissions of this user based on the security policies attached to them. clientId string  UUID ~ 256 chars Client ID Result Type Description item Identifier Credential Implementation Example describeAttachedGuards Get a list of assigned GS2-Guard Namespace GRNs Retrieves the list of GS2-Guard namespaces attached to the specified credential. When guards are attached, API requests using this credential are subject to additional access control checks defined by the guard service (e.g., IP-based blocking). Details Request  clientId string  UUID ~ 256 chars Client ID userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of GS2-Guard Namespace GRN Implementation Example attachGuard Assign the GS2-Guard Namespace GRN to the credential Attaches a GS2-Guard namespace to the specified credential for additional access control. Once attached, API requests using this credential will be validated against the guard’s blocking policies (e.g., IP detection, anonymous IP filtering, reputation-based filtering). Returns the complete list of guard namespaces attached to the credential after the operation. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clientId string  UUID ~ 256 chars Client ID guardNamespaceId string  ~ 1024 chars Assign GS2-Guard Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description items List List of GS2-Guard Namespace GRN Implementation Example detachGuard Remove GS2-Guard Namespace GRN from the credential Removes a GS2-Guard namespace from the specified credential. After removal, API requests using this credential will no longer be subject to the guard’s access control checks. Returns the list of remaining guard namespaces attached to the credential. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clientId string  UUID ~ 256 chars Client ID guardNamespaceId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Guard Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description items List List of GS2-Guard Namespace GRN Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example createPassword Create a new password Creates password credentials for the specified GS2-Identifier user. Once created, the user can authenticate using their username and password via the LoginByUser API to obtain a project token. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. password string  ~ 1024 chars Password The hashed password used for management console authentication. Set during password creation and verified against user input at login time. Stored internally and never returned through the API. Result Type Description item Password Created Password Implementation Example getPassword Get Password Retrieves the password metadata for the specified user. The actual password value is not returned; only metadata such as MFA settings and creation time are included. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. Result Type Description item Password Password Implementation Example enableMfa Enable MFA Initiates the setup of TOTP (Time-based One-Time Password) -based multi-factor authentication for the specified user. Generates a TOTP secret key and sets the MFA status to “Verifying”. Returns a challenge token that must be used with the ChallengeMfa API to complete the setup by verifying a TOTP passcode. If MFA is already enabled, an error is returned. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. Result Type Description item Password Password updated challengeToken string Challenge Token Implementation Example challengeMfa Verify the effectiveness of MFA Completes the MFA setup by verifying a 6-digit TOTP (Time-based One-Time Password) code. The MFA status must be “Verifying” (set by EnableMfa); otherwise, an error is returned. Upon successful verification, the MFA status is changed to “Enable”, and subsequent logins via LoginByUser will require a TOTP passcode. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. passcode string  6 ~ 6 chars One-time password code Result Type Description item Password Password updated Implementation Example disableMfa Disable MFA Disables multi-factor authentication for the specified user. Clears the TOTP secret key and MFA settings. Subsequent logins will only require password authentication. If MFA is already disabled, an error is returned. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. Result Type Description item Password Password updated Implementation Example deletePassword Delete password Deletes the password credentials for the specified user. After deletion, the user can no longer authenticate via the LoginByUser API. MFA settings are also removed. Credential-based authentication (client ID/secret) via the Login API is not affected. Details Request  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. Result Type Description item Password Password Implementation Example getHasSecurityPolicy Get a list of assigned Security Policies Retrieves all security policies currently attached to the specified user. The combined set of attached policies determines the user’s effective API permissions. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Security Policies Implementation Example attachSecurityPolicy Assign the Security Policy to a user Attaches a security policy to the specified user by its GRN. The policy is loaded and validated before attachment. Both custom policies and GS2-defined common policies can be attached. A user can have multiple policies attached; the effective permissions are the union of all attached policies. Returns the complete list of security policies currently attached to the user after the operation. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). securityPolicyId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Security Policy to assign Result Type Description items List List of Security Policies assigned to a user Implementation Example detachSecurityPolicy Revoke assigned Security Policies from a user Detaches a security policy from the specified user by its GRN. After detachment, the user loses the permissions granted by this policy. Returns the list of security policies that remain attached to the user after the operation. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). securityPolicyId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the Security Policy to be revoked Result Type Description items List List of Security Policies that remain assigned to the user after deactivation Implementation Example describeUsers Retrieves list of users Retrieves a paginated list of GS2-Identifier users under the current project. Users are entities that can hold credentials (client ID/secret), passwords, and security policies for API access control. Details Request  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 List of Users nextPageToken string Page token to retrieve the rest of the listing Implementation Example createUser Create a new user Creates a new GS2-Identifier user with the specified name and description. After creation, you can assign credentials, passwords, and security policies to control API access permissions. Details Request  name string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description Result Type Description item User Created User Implementation Example updateUser Update user Updates the description of an existing GS2-Identifier user. The user name cannot be changed after creation. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description Result Type Description item User Users after update Implementation Example getUser Retrieve the user Retrieves the detailed information of a specific GS2-Identifier user by user name. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item User user Implementation Example deleteUser Delete user Deletes a GS2-Identifier user and all associated data including credentials, passwords, and security policy attachments. Details Request  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item User User deleted Implementation Example describeSecurityPolicies Get a list of security policies Retrieves a paginated list of custom security policies defined in the current project. Security policies are JSON documents that define authorization rules controlling which GS2 API operations a user is allowed to perform. Details Request  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 List of security policies nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeCommonSecurityPolicies Get a list of GS2-defined security policies Retrieves a paginated list of built-in security policies provided by GS2. These common policies cover typical use cases and can be attached to users alongside custom policies. Details Request  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 List of security policies nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSecurityPolicy Create a new Security Policy Creates a new custom security policy with a name, description, and JSON policy document. The policy document defines the authorization rules that control which GS2 API operations are allowed or denied. After creation, the policy can be attached to users via the AttachSecurityPolicy API. Details Request  name string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description policy string  ~ 524288 chars Policy Document A JSON document that defines the access control rules for this security policy. The document specifies which GS2 API actions are allowed or denied, and which resources (identified by GRN patterns) the rules apply to. Multiple statements can be combined to create fine-grained access control. Maximum 512KB. Result Type Description item SecurityPolicy Created security policy Implementation Example updateSecurityPolicy Update Security Policy Updates the description and policy document of an existing security policy. Changes take effect immediately for all users who have this policy attached. The policy name cannot be changed after creation. Details Request  securityPolicyName string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description policy string  ~ 524288 chars Policy Document A JSON document that defines the access control rules for this security policy. The document specifies which GS2 API actions are allowed or denied, and which resources (identified by GRN patterns) the rules apply to. Multiple statements can be combined to create fine-grained access control. Maximum 512KB. Result Type Description item SecurityPolicy Security Policy updated Implementation Example getSecurityPolicy Get Security Policy Retrieves the detailed information of a specific security policy, including its JSON policy document. Details Request  securityPolicyName string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SecurityPolicy Security Policy Implementation Example deleteSecurityPolicy Delete Security Policy Deletes a custom security policy. If this policy is still attached to any users, those users will lose the permissions granted by this policy. Details Request  securityPolicyName string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SecurityPolicy Security Policy Implementation Example login Get a Project Token Authenticates using OAuth2 client credentials (client ID and client secret) and returns a project token (Bearer token). The client secret is verified against the stored credential; if invalid, an Unauthorized error is returned. The returned token has a validity period of 36000 seconds (10 hours) and is used as the Bearer token for all subsequent GS2 API requests. Details Request  client_id string  UUID ~ 256 chars Client ID client_secret string  UUID ~ 100 chars Client Secret Result Type Description access_token string Project Token token_type string Bearer expires_in int Period of validity(sec) Implementation Example loginByUser Get a Project Token by specifying a GS2-Identifier user Authenticates using a GS2-Identifier username and password, and returns a project token. If multi-factor authentication (MFA) is enabled for the user, a valid TOTP passcode must also be provided in the otp field; if missing, a “require” error is returned. The password is verified first, followed by the TOTP passcode if MFA is enabled. Details Request  userName string  ~ 128 chars GS2-Identifier username password string  ~ 1024 chars Password for GS2-Identifier user otp string 6 ~ 6 chars Passcode Result Type Description item ProjectToken Project Token Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Identifier SDK for various programming languages\n","title":"GS2-Identifier SDK API Reference","url":"/api_reference/identifier/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting idle rewards. receiveScript ScriptSetting Script setting executed when rewards are received Script Trigger Reference - receive overrideAcquireActionsScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN for dynamically determining idle reward Acquire Actions Script Trigger Reference - overrideAcquireActions logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to idle reward operations. Useful for tracking idle status creation, reward claims, and debugging timing issues. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Status Status Created when GetIdleStatus is called for the first time, and the idle time count starts from that time. The idle time count is reset when you receive a reward. If GS2-Schedule events are associated, you cannot access Category before the event is held, and you cannot create a status. If an event is associated, the status holds the number of repetitions of the event. If the current event ID and the event ID at the time of status creation do not match, if the number of repetitions of the current event and the number of repetitions held by the status do not match, or if the status is created before the start time of the event, the waiting time is reset. Details  statusId string * ~ 1024 chars Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. userId string  ~ 128 chars User ID randomSeed long 0 0 ~ 9223372036854775805 Random Seed A seed value used for deterministic random number generation when calculating idle rewards. Ensures that reward calculations are reproducible and consistent, allowing the server to verify reward results. Updated each time rewards are received. idleMinutes int  0 ~ 2147483646 Idle Minutes The accumulated idle time in minutes since the last reward claim or status creation. This value is calculated from the elapsed time since idleStartedAt and is capped at maximumIdleMinutes. The number of available rewards is determined by dividing this value by the category model’s rewardIntervalMinutes. nextRewardsAt long Time when additional rewards can be obtained next Unix time, milliseconds maximumIdleMinutes int 0 0 ~ 2147483646 Maximum Idle Minutes The maximum idle time in minutes that this status can accumulate. Initialized from the category model’s defaultMaximumIdleMinutes when the status is created. Can be increased per-user via acquire actions, allowing premium users or event participants to accumulate more idle rewards. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision CategoryModel Category Model A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time. Details  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value AcquireAction Acquire Action Represents a single acquire action used as an idle reward. Consists of an action type (e.g., add items, increase currency) and its request parameters. When idle rewards are claimed, these actions are assembled into transactions and executed to deliver the rewards to the user. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireActionList Acquire Action List A wrapper that groups multiple acquire actions to be granted together for a single reward interval. Each AcquireActionList corresponds to one reward cycle in the category model’s acquireActions array, enabling different reward combinations at each interval. Details  acquireActions List [] 0 ~ 100 items List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. CurrentCategoryMaster Currently active Category Model master data This master data defines the Category Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Idle Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data CategoryModelMaster Category Model Master Category Model Master is data used to edit and manage Category Models within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Category Model actually referenced by the game. A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time. Details  categoryModelId string * ~ 1024 chars Category Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new namespace for the GS2-Idle service. You can configure transaction settings, a receiveScript (executed before granting idle rewards to validate or modify the operation), an overrideAcquireActionsScriptId (to modify acquire actions such as applying rate modifiers), and log settings. After creation, you need to set up category models via master data to define idle reward configurations. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting idle rewards. receiveScript ScriptSetting Script setting executed when rewards are received Script Trigger Reference - receive overrideAcquireActionsScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN for dynamically determining idle reward Acquire Actions logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to idle reward operations. Useful for tracking idle status creation, reward claims, and debugging timing issues. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the settings of the specified namespace. You can modify the description, transaction settings, receiveScript (executed before granting idle rewards), overrideAcquireActionsScriptId (to modify acquire actions), and log settings. Changes take effect immediately for subsequent operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting idle rewards. receiveScript ScriptSetting Script setting executed when rewards are received Script Trigger Reference - receive overrideAcquireActionsScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN for dynamically determining idle reward Acquire Actions logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to idle reward operations. Useful for tracking idle status creation, reward claims, and debugging timing issues. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Returns the URL of the output data when the dump is complete. If the dump is still in progress, the URL will be empty. The dumped data includes all idle status records for the specified user, compressed in gzip format. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Returns completion status of the clean operation. The clean operation deletes all idle status records for the specified user across all namespaces owned by the same owner. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Returns completion status and a URL to the import log when available. The import processes the uploaded ZIP file containing idle status data, validates the JSON structure, and restores the records for the specified user. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeStatuses Get a list of statuses Retrieves a paginated list of idle statuses for the authenticated user in the specified namespace. Each status represents a per-category idle state, including the time when idle accumulation started and the current maximum idle time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStatusesByUserId Get a list of statuses by specifying a user ID Retrieves a paginated list of idle statuses for the specified user. Each status represents a per-category idle state, including the time when idle accumulation started and the current maximum idle time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Status nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStatus Get Status Retrieves the idle status for a specific category of the authenticated user. If no status record exists yet, the status is automatically created with the current time as the idle start time and the category model’s defaultMaximumIdleMinutes as the maximum idle time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. Result Type Description item Status Status Implementation Example getStatusByUserId Get status by specifying a user ID Retrieves the idle status for a specific category of the specified user. If no status record exists yet, the status is automatically created with the current time as the idle start time and the category model’s defaultMaximumIdleMinutes as the maximum idle time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example prediction Get a list of rewards Calculates and returns the rewards that would be received based on the current idle time without actually receiving them. The calculation is based on the elapsed idle time divided by the rewardIntervalMinutes, capped by the maximumIdleMinutes. This is a read-only operation that does not modify the status or reset the idle timer. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. Result Type Description items List Rewards status Status Status Implementation Example predictionByUserId Get a list of rewards by specifying a user ID Calculates and returns the rewards that would be received for the specified user based on their current idle time without actually receiving them. The calculation is based on the elapsed idle time divided by the rewardIntervalMinutes, capped by the maximumIdleMinutes. This is a read-only operation that does not modify the status or reset the idle timer. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Rewards status Status Status Implementation Example receive Receive rewards Receives idle rewards for the specified category based on the accumulated idle time. The reward amount is calculated from the elapsed idle time divided by rewardIntervalMinutes, capped by maximumIdleMinutes. If a receiveScript is configured, it is executed before granting rewards and can modify or reject the receive operation. An overrideAcquireActionsScriptId can also modify the acquire actions (e.g., applying rate modifiers). After receiving, the idle timer is reset to the current time. If rewardResetMode is set, the idle timer behavior may vary. Returns a transaction containing the acquire actions for the calculated rewards. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description items List Rewards status Status Status updated transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example receiveByUserId Receive rewards by specifying a user ID Receives idle rewards for the specified user and category based on the accumulated idle time. The reward amount is calculated from the elapsed idle time divided by rewardIntervalMinutes, capped by maximumIdleMinutes. If a receiveScript is configured, it is executed before granting rewards and can modify or reject the receive operation. An overrideAcquireActionsScriptId can also modify the acquire actions (e.g., applying rate modifiers). After receiving, the idle timer is reset to the current time. Returns a transaction containing the acquire actions for the calculated rewards. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List Rewards status Status Status updated transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example increaseMaximumIdleMinutesByUserId Increase the maximum idle time by specifying a user ID Adds the specified number of minutes to the user’s maximum idle time for the given category. The maximum idle time determines the cap on how long idle rewards can accumulate. If no status exists yet, it is automatically created before applying the increase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. increaseMinutes int 1 ~ 2147483646 Minutes to increase the maximum idle time timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated Implementation Example decreaseMaximumIdleMinutes Decrease the maximum idle time Subtracts the specified number of minutes from the authenticated user’s maximum idle time for the given category. The maximum idle time cannot go below zero. If no status exists yet, it is automatically created before applying the decrease. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. decreaseMinutes int 1 ~ 2147483646 Minutes to decrease the maximum idle time Result Type Description item Status Status updated Implementation Example decreaseMaximumIdleMinutesByUserId Decrease the maximum idle time by specifying a user ID Subtracts the specified number of minutes from the user’s maximum idle time for the given category. The maximum idle time cannot go below zero. If no status exists yet, it is automatically created before applying the decrease. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. decreaseMinutes int 1 ~ 2147483646 Minutes to decrease the maximum idle time timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated Implementation Example setMaximumIdleMinutesByUserId Set the maximum idle time by specifying a user ID Sets the user’s maximum idle time for the given category to the specified absolute value. Unlike increase/decrease operations, this directly replaces the current maximum idle time. Returns both the updated status and the status before the update, allowing the caller to see what changed. If no status exists yet, it is automatically created before applying the value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. maximumIdleMinutes int 1 ~ 2147483646 Maximum idle time to set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status updated old Status Status before update Implementation Example describeCategoryModels Get a list of Category Models Retrieves the list of currently active (published) category models in the specified namespace. These are the models that have been activated via the master data update process and define the idle reward configuration available to players. Each model contains settings such as reward interval, maximum idle time, reward reset mode, acquire actions, and schedule references. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Model Implementation Example getCategoryModel Get Category Model Retrieves the details of a specific active category model by name. The model defines the idle reward configuration including rewardIntervalMinutes (how often rewards accumulate), defaultMaximumIdleMinutes (cap on idle time), acquireActions (rewards to grant), and optional schedule references for controlling idle and receive periods. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModel Category Model Implementation Example exportMaster Export Category Model Master in a master data format that can be activated Exports all category model masters in the namespace as a JSON document suitable for activation. The exported data includes the complete configuration of each category model (reward interval, maximum idle time, reward reset mode, acquire actions, schedule references). This data can be used to activate the master data in another namespace or stored for version control purposes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentCategoryMaster Category Model master data that can be activated Implementation Example getCurrentCategoryMaster Get currently active Category Model master data Retrieves the currently active master data that defines which category models are available in the namespace. This is the data that was last activated and is being used to serve category model requests to players. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentCategoryMaster Currently active Category Model master data Implementation Example preUpdateCurrentCategoryMaster Update currently active Category Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentCategoryMaster Update currently active Category Model master data Activates new master data to replace the currently active category models. Supports two modes: “direct” for inline JSON data (suitable for small payloads), and “preUpload” for data uploaded via a presigned URL (required for data exceeding 1MB, using the token obtained from PreUpdate). After activation, the new category models become immediately available for idle reward processing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentCategoryMaster Updated master data of the currently active Category Models Implementation Example updateCurrentCategoryMasterFromGitHub Update currently active Category Model master data from GitHub Fetches master data from a GitHub repository and activates it as the current category model configuration. The checkout setting specifies the repository, branch/tag, and file path to retrieve the master data JSON. This enables GitOps-style management of idle reward configurations with version control. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentCategoryMaster Updated master data of the currently active Category Models Implementation Example describeCategoryModelMasters Get a list of Category Model Masters Retrieves a paginated list of editable category model masters in the specified namespace. Category model masters are the editable versions of category models that define idle reward configurations. Changes to masters do not take effect until they are activated through the current master data update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Category Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createCategoryModelMaster Create a new Category Model Master Creates a new editable category model master that defines an idle reward configuration. Key settings include rewardIntervalMinutes (how often rewards accumulate), defaultMaximumIdleMinutes (cap on idle time), rewardResetMode (whether rewards reset on receive), and acquireActions (the rewards to grant). Optionally, idlePeriodScheduleId and receivePeriodScheduleId can reference GS2-Schedule events to control when idle accumulation and reward receipt are active. The created master must be activated through the current master data update process to take effect. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. Result Type Description item CategoryModelMaster Category Model Master created Implementation Example getCategoryModelMaster Get Category Model Master Retrieves the details of a specific editable category model master. Returns the full configuration including reward interval, maximum idle time, reward reset mode, acquire actions, and schedule references. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModelMaster Category Model Master Implementation Example updateCategoryModelMaster Update Category Model Master Updates the configuration of an existing category model master. You can modify the reward interval, maximum idle time, reward reset mode, acquire actions, and schedule references. Changes do not affect the currently active model until the master data is re-activated through the update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. Result Type Description item CategoryModelMaster Category Model Master updated Implementation Example deleteCategoryModelMaster Delete Category Model Master Deletes the specified category model master. This does not affect the currently active model; the deletion takes effect only after the master data is re-activated. Existing user statuses associated with this category are not automatically deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModelMaster Category Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Idle SDK for various programming languages\n","title":"GS2-Idle SDK API Reference","url":"/api_reference/idle/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description isAutomaticDeletingEnabled bool false Automatic Deletion When enabled, messages are automatically removed from the user’s message list after they are opened (read). This keeps the inbox clean by removing claimed messages without requiring an explicit delete operation from the client. When disabled, opened messages remain in the list until manually deleted. transactionSetting TransactionSetting Transaction Setting Configuration for distributed transaction processing (transactions) used when granting rewards attached to messages. When a message with readAcquireActions is opened, transactions are generated and executed to deliver the rewards. Supports auto-run, atomic commit, and asynchronous processing. receiveMessageScript ScriptSetting Script to run when a message is received Script Trigger Reference - receiveMessage readMessageScript ScriptSetting Script to run when a message is opened Script Trigger Reference - readMessage deleteMessageScript ScriptSetting Script to run when a message is deleted Script Trigger Reference - deleteMessage receiveNotification NotificationSetting Receive Notification Push Notification Setting triggered when a new message is delivered to a user’s inbox. Uses GS2-Gateway to send real-time notifications to the game client, allowing the UI to display a new message indicator or refresh the inbox without polling. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to message operations. Useful for tracking message delivery, opening, reward claims, and deletion for auditing and debugging purposes. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Message Message Message data delivered to a message box prepared for each game player. Messages have an open state, and you can set an Acquire Action to be executed when opened. Messages can be set to expire, and messages that expire are automatically deleted regardless of whether they are unread or read after opening. Messages will be deleted even if you have not received the attached reward. Details  messageId string * ~ 1024 chars Message A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. userId string  ~ 128 chars User ID metadata string  ~ 4096 chars Metadata Arbitrary data representing the message content, such as a JSON string containing the message title, body text, sender information, and display parameters. GS2 does not interpret this value; it is passed through to the game client for rendering the message UI. Maximum 4096 characters. isRead bool false Read Status Indicates whether the message has been opened by the user. When a message is opened, this flag is set to true, the readAcquireActions are executed to deliver attached rewards, and the readAt timestamp is recorded. If isAutomaticDeletingEnabled is set on the namespace, the message is deleted after being read. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions executed when the user opens this message. Used to attach rewards such as items, currency, or resources to messages. Multiple actions can be combined to grant different reward types simultaneously. Up to 100 actions per message. receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server readAt long 0 Datetime of read Unix time, milliseconds expiresAt long Expiration datetime Unix time, milliseconds revision long 0 0 ~ 9223372036854775805 Revision GlobalMessage Global Message Global Message is a mechanism for delivering messages to all game players. Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message. Unreceived Global Messages within the validity period are copied to the player’s message box. Details  globalMessageId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Global Message for all users * Set automatically by the server name string  ~ 128 chars Global Message name Global Message-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. Received Received Global Message Tracks which global messages a user has already received to prevent duplicate delivery. When a user triggers the receive global messages operation, the system checks this record to skip already-received messages. Each user has one Received record that accumulates the names of all global messages they have copied to their inbox. Details  receivedId string * ~ 1024 chars Received Global Message name A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID receivedGlobalMessageNames List [] 0 ~ 100 items Received Global Message Names The list of global message names that the user has already received. When the receive global messages operation is executed, messages whose names appear in this list are skipped. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TimeSpan Time Span Represents a duration of time as a combination of days, hours, and minutes. Used to define the expiration period for messages relative to their reception time. For example, a TimeSpan of 7 days, 0 hours, 0 minutes means the message expires exactly one week after the user receives it. Details  days int 0 0 ~ 365 Days The number of days in this time span. Combined with hours and minutes to calculate the total duration. Maximum 365 days. hours int 0 0 ~ 24 Hours The number of hours in this time span. Combined with days and minutes to calculate the total duration. Maximum 24 hours. minutes int 0 0 ~ 60 Minutes The number of minutes in this time span. Combined with days and hours to calculate the total duration. Maximum 60 minutes. AcquireAction Acquire Action Represents a single acquire action attached to a message as a reward. Consists of an action type (e.g., add items to inventory, increase currency) and its request parameters. When a message is opened, these actions are assembled into transactions and executed to deliver the rewards to the user. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentMessageMaster Currently active Global Message master data This master data defines the Global Messages currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Inbox Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data GlobalMessageMaster Global Message Master Global Message Master is data used to edit and manage Global Message within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Global Message actually referenced by the game. Global messaging is a mechanism for delivering messages to all game players. Global Messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message. Unreceived Global Messages within the validity period are copied to the player’s message box. Details  globalMessageId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Global Message for all users * Set automatically by the server name string  UUID ~ 64 chars Global Message Name A unique identifier for this global message within the namespace. Used to track which global messages each user has already received, preventing duplicate delivery. Automatically generated as a UUID if not specified. metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new namespace for the GS2-Inbox service. You can configure isAutomaticDeletingEnabled (whether read messages are automatically deleted), transaction settings, script callbacks (receiveMessageScript, readMessageScript, deleteMessageScript), receiveNotification (webhook for message events), and log settings. After creation, you can define global message masters and activate them through the master data update process. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description isAutomaticDeletingEnabled bool false Automatic Deletion When enabled, messages are automatically removed from the user’s message list after they are opened (read). This keeps the inbox clean by removing claimed messages without requiring an explicit delete operation from the client. When disabled, opened messages remain in the list until manually deleted. transactionSetting TransactionSetting Transaction Setting Configuration for distributed transaction processing (transactions) used when granting rewards attached to messages. When a message with readAcquireActions is opened, transactions are generated and executed to deliver the rewards. Supports auto-run, atomic commit, and asynchronous processing. receiveMessageScript ScriptSetting Script to run when a message is received Script Trigger Reference - receiveMessage readMessageScript ScriptSetting Script to run when a message is opened Script Trigger Reference - readMessage deleteMessageScript ScriptSetting Script to run when a message is deleted Script Trigger Reference - deleteMessage receiveNotification NotificationSetting Receive Notification Push Notification Setting triggered when a new message is delivered to a user’s inbox. Uses GS2-Gateway to send real-time notifications to the game client, allowing the UI to display a new message indicator or refresh the inbox without polling. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to message operations. Useful for tracking message delivery, opening, reward claims, and deletion for auditing and debugging purposes. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the settings of the specified namespace. You can modify the description, automatic deletion setting, transaction settings, script callbacks (receiveMessageScript, readMessageScript, deleteMessageScript), receiveNotification, and log settings. Changes take effect immediately for subsequent operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description isAutomaticDeletingEnabled bool false Automatic Deletion When enabled, messages are automatically removed from the user’s message list after they are opened (read). This keeps the inbox clean by removing claimed messages without requiring an explicit delete operation from the client. When disabled, opened messages remain in the list until manually deleted. transactionSetting TransactionSetting Transaction Setting Configuration for distributed transaction processing (transactions) used when granting rewards attached to messages. When a message with readAcquireActions is opened, transactions are generated and executed to deliver the rewards. Supports auto-run, atomic commit, and asynchronous processing. receiveMessageScript ScriptSetting Script to run when a message is received Script Trigger Reference - receiveMessage readMessageScript ScriptSetting Script to run when a message is opened Script Trigger Reference - readMessage deleteMessageScript ScriptSetting Script to run when a message is deleted Script Trigger Reference - deleteMessage receiveNotification NotificationSetting Receive Notification Push Notification Setting triggered when a new message is delivered to a user’s inbox. Uses GS2-Gateway to send real-time notifications to the game client, allowing the UI to display a new message indicator or refresh the inbox without polling. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to message operations. Useful for tracking message delivery, opening, reward claims, and deletion for auditing and debugging purposes. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Returns the URL of the output data when the dump is complete. If the dump is still in progress, the URL will be empty. The dumped data includes all message records and received global message tracking for the specified user, compressed in gzip format. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Returns completion status of the clean operation. The clean operation deletes all message records and received global message tracking for the specified user across all namespaces owned by the same owner. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Returns completion status and a URL to the import log when available. The import processes the uploaded ZIP file containing inbox data (inbox.json), validates each record’s structure and data type (Message or Received), and restores the records for the specified user. Template variables in the data are automatically replaced during import. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeMessages Get a list of messages Retrieves a paginated list of messages in the authenticated user’s inbox. Optionally filter by read status using the isRead parameter; if not specified, all messages are returned regardless of read status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token isRead bool? Read status 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 List of Message nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeMessagesByUserId Get a list of messages by specifying a user ID Retrieves a paginated list of messages in the specified user’s inbox. Optionally filter by read status using the isRead parameter; if not specified, all messages are returned regardless of read status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID isRead bool? Read status 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Message nextPageToken string Page token to retrieve the rest of the listing Implementation Example sendMessageByUserId Send a message by specifying a user ID Creates and delivers a new message to the specified user’s inbox. The message can include metadata (arbitrary JSON content) and readAcquireActions (rewards granted when the message is read). Message expiration can be set using either an absolute timestamp (expiresAt) or a relative duration (expiresTimeSpan) from the time of delivery. If expiresAt is specified, it takes priority over expiresTimeSpan. The message starts in an unread state (isRead=false). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID metadata string  ~ 4096 chars Metadata Arbitrary data representing the message content, such as a JSON string containing the message title, body text, sender information, and display parameters. GS2 does not interpret this value; it is passed through to the game client for rendering the message UI. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions executed when the user opens this message. Used to attach rewards such as items, currency, or resources to messages. Multiple actions can be combined to grant different reward types simultaneously. Up to 100 actions per message. expiresAt long Expiration datetime Unix time, milliseconds expiresTimeSpan TimeSpan The period from the time a message was received (reference time) until it was deleted timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message created Implementation Example getMessage Get Message Retrieves the details of a specific message from the authenticated user’s inbox, including its metadata, read status, and configured acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. Result Type Description item Message Message Implementation Example getMessageByUserId Get message by specifying a user ID Retrieves the details of a specific message from the specified user’s inbox, including its metadata, read status, and configured acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message Implementation Example receiveGlobalMessage Receive Global Message that have not yet been received Converts active global messages into individual messages in the authenticated user’s inbox. Compares the list of active global messages against the user’s received tracking record to identify undelivered messages, and creates new message copies only for those not yet received. The received tracking record is updated to prevent duplicate delivery on subsequent calls. Returns the list of newly created messages. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item List List of received messages Implementation Example receiveGlobalMessageByUserId Receive Global Message that have not yet been received by specifying the user ID Converts active global messages into individual messages in the specified user’s inbox. Compares the list of active global messages against the user’s received tracking record to identify undelivered messages, and creates new message copies only for those not yet received. The received tracking record is updated to prevent duplicate delivery on subsequent calls. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item List List of received messages Implementation Example openMessage Marking messages as opened Marks the specified message as read (opened) in the authenticated user’s inbox. This is a simple state transition that sets isRead to true without executing any acquire actions. To mark as read and also execute associated rewards, use the Read API instead. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. Result Type Description item Message Message Implementation Example openMessageByUserId Marking messages as opened by specifying a user ID Marks the specified message as read (opened) in the specified user’s inbox. This is a simple state transition that sets isRead to true without executing any acquire actions. To mark as read and also execute associated rewards, use the Read API instead. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message Implementation Example closeMessageByUserId Mark a previously opened message as unread Reverts the read status of a message back to unread (isRead=false). This is the inverse operation of Open, allowing messages to be returned to the unread state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message Implementation Example readMessage Read message Marks the message as read and executes the configured readAcquireActions (rewards). If the message has already been read, an “alreadyRead” error is returned to prevent duplicate reward grants. If the message has no acquire actions, it is simply marked as read without generating a transaction. If acquire actions are present, a transaction is returned for executing the reward transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Message Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example readMessageByUserId Read message by specifying a user ID Marks the message as read and executes the configured readAcquireActions (rewards) for the specified user. If the message has already been read, an “alreadyRead” error is returned to prevent duplicate reward grants. If the message has no acquire actions, it is simply marked as read without generating a transaction. If acquire actions are present, a transaction is returned for executing the reward transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example batchReadMessages Read messages Atomically reads multiple messages at once, marking them as read and executing their combined readAcquireActions (rewards). If any of the specified messages has already been read, an “alreadyRead” error is returned and no messages are processed. Messages without acquire actions are marked as read immediately, while messages with rewards are processed together in a single transaction. Up to 10 messages can be read in a single batch operation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token messageNames List  1 ~ 10 items List of message names config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description items List List of Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example batchReadMessagesByUserId Read messages by specifying a user ID Atomically reads multiple messages at once for the specified user, marking them as read and executing their combined readAcquireActions (rewards). If any of the specified messages has already been read, an “alreadyRead” error is returned and no messages are processed. Messages without acquire actions are marked as read immediately, while messages with rewards are processed together in a single transaction. Up to 10 messages can be read in a single batch operation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageNames List  1 ~ 10 items List of message names config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Message transactionId string Issued transaction ID stampSheet string Stamp sheet stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example deleteMessage Delete message Permanently removes a message from the authenticated user’s inbox. The message record is deleted regardless of its read status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. Result Type Description item Message Message deleted Implementation Example deleteMessageByUserId Delete message by specifying a user ID Permanently removes a message from the specified user’s inbox. The message record is deleted regardless of its read status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Message Message deleted Implementation Example describeGlobalMessages Get a list of messages to all users Retrieves the list of currently active global messages in the specified namespace. Only messages within their reception period are returned; messages outside their reception window are excluded. Global messages are broadcast messages that can be converted into individual user messages via the ReceiveGlobalMessage API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Message to all users Implementation Example getGlobalMessage Get a message for all users Retrieves a specific global message by name. The message must be within its reception period; if the message is outside the reception window, a 404 error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). globalMessageName string  ~ 128 chars Global Message name Global Message-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GlobalMessage Message to all users Implementation Example getReceivedByUserId Get Received Global Message by specifying a user ID Retrieves the list of global message names that the specified user has already received. This tracking record is used by ReceiveGlobalMessage to determine which global messages have not yet been delivered to the user, preventing duplicate delivery. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Received Received Global Message Implementation Example updateReceivedByUserId Update Received Global Message by specifying a user ID Directly updates the list of global message names that the user has received. This can be used to manually mark specific global messages as received or to reset the received state for re-delivery. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID receivedGlobalMessageNames List [] 0 ~ 100 items Received Global Message Names The list of global message names that the user has already received. When the receive global messages operation is executed, messages whose names appear in this list are skipped. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Received Received Global Message updated Implementation Example deleteReceivedByUserId Delete Received Global Message by specifying a user ID Deletes the received tracking record for the specified user. After deletion, the next call to ReceiveGlobalMessage will treat all active global messages as unreceived and deliver them again as individual messages. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Received Received Global Message Implementation Example exportMaster Export Global Message Master in a master data format that can be activated Exports all global message masters in the namespace as a JSON document suitable for activation. The exported data includes the complete configuration of each global message (metadata, read acquire actions, expiration settings, reception period references). This data can be used to activate the master data in another namespace or stored for version control purposes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentMessageMaster Global Message master data that can be activated Implementation Example getCurrentMessageMaster Get currently active Global Message master data Retrieves the currently active master data that defines which global messages are available in the namespace. This is the data that was last activated and is being used to serve global message requests and ReceiveGlobalMessage operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentMessageMaster Currently active Global Message master data Implementation Example preUpdateCurrentMessageMaster Update Currently Active Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentMessageMaster Update currently active Global Message master data Activates new master data to replace the currently active global messages. Supports two modes: “direct” for inline JSON data (suitable for small payloads), and “preUpload” for data uploaded via a presigned URL (required for data exceeding 1MB, using the token obtained from PreUpdate). After activation, the new global messages become immediately available for ReceiveGlobalMessage operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentMessageMaster Updated master data of the currently active Global Messages Implementation Example updateCurrentMessageMasterFromGitHub Update currently active Global Message master data from GitHub Fetches master data from a GitHub repository and activates it as the current global message configuration. The checkout setting specifies the repository, branch/tag, and file path to retrieve the master data JSON. Template variables (region, ownerId, userId) in the file are automatically replaced during processing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentMessageMaster Updated master data of the currently active Global Messages Implementation Example describeGlobalMessageMasters Get a list of messages to all users Retrieves a paginated list of all global message masters in the specified namespace, regardless of their reception period. This is an administrative view that shows all defined global messages, including those not yet active or already expired. Supports optional name prefix filtering for targeted searches. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by messages to all users prefix 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 List of messages for all users nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGlobalMessageMaster Create a new message for all users Creates a new global message template that will be broadcast to all users. You can configure readAcquireActions (rewards granted when the message is read), and message expiration using either an absolute timestamp (expiresAt) or a relative duration (expiresTimeSpan) from when the user receives the message. Optionally, messageReceptionPeriodEventId can reference a GS2-Schedule event to control the time window during which the message can be received by users. The created master must be activated through the current master data update process to become available to users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  UUID ~ 64 chars Global Message Name A unique identifier for this global message within the namespace. Used to track which global messages each user has already received, preventing duplicate delivery. Automatically generated as a UUID if not specified. metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. Result Type Description item GlobalMessageMaster Message to all users created Implementation Example getGlobalMessageMaster Get a message for all users Retrieves the details of a specific global message master, including its metadata, read acquire actions, expiration settings, and reception period configuration. Unlike the GlobalMessage Get API, this returns the message regardless of whether it is within the reception period. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). globalMessageName string  UUID ~ 64 chars Global Message Name A unique identifier for this global message within the namespace. Used to track which global messages each user has already received, preventing duplicate delivery. Automatically generated as a UUID if not specified. Result Type Description item GlobalMessageMaster Message to all users Implementation Example updateGlobalMessageMaster Update message to all users Updates the properties of an existing global message master. You can modify the metadata, read acquire actions (rewards), expiration settings, and reception period event reference. Changes must be activated through the current master data update process to take effect. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). globalMessageName string  UUID ~ 64 chars Global Message Name A unique identifier for this global message within the namespace. Used to track which global messages each user has already received, preventing duplicate delivery. Automatically generated as a UUID if not specified. metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. Result Type Description item GlobalMessageMaster Updated message to all users Implementation Example deleteGlobalMessageMaster Delete messages for all users Deletes the specified global message master. After activation of the master data update, the message will no longer be available for new user receptions. Messages that have already been received by users as individual messages are not affected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). globalMessageName string  UUID ~ 64 chars Global Message Name A unique identifier for this global message within the namespace. Used to track which global messages each user has already received, preventing duplicate delivery. Automatically generated as a UUID if not specified. Result Type Description item GlobalMessageMaster Deleted Message to all users Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Inbox SDK for various programming languages\n","title":"GS2-Inbox SDK API Reference","url":"/api_reference/inbox/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configures distributed transaction processing for inventory operations such as acquiring and consuming items. Supports auto-run mode for seamless execution, atomic commit for consistent multi-resource operations, and async processing for large-scale reward distribution. acquireScript ScriptSetting Script setting to be executed when an Items is acquired Script Trigger Reference - acquire overflowScript ScriptSetting Script to execute when unable to obtain due to reaching the acquisition limit Script Trigger Reference - overflowDone consumeScript ScriptSetting Script to run when consuming Items Script Trigger Reference - consume simpleItemAcquireScript ScriptSetting Script setting to be executed when acquiring Simple Items Script Trigger Reference - simpleItemAcquire simpleItemConsumeScript ScriptSetting Script to run when consuming Simple Items Script Trigger Reference - simpleItemConsume bigItemAcquireScript ScriptSetting Script setting to be executed when acquiring Big Items Script Trigger Reference - bigItemAcquire bigItemConsumeScript ScriptSetting Script to run when consuming Big Items Script Trigger Reference - bigItemConsume logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of inventory operations. Useful for tracking item acquisition, consumption, and capacity changes for debugging and analytics. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Inventory Inventory Inventory is like a bag that stores items owned by game players. The bag has a capacity, and the capacity can be expanded by each player. Details  inventoryId string * ~ 1024 chars Inventory A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID currentInventoryCapacityUsage int 0 0 ~ 2147483646 Capacity Usage The number of inventory slots currently occupied by item sets. Incremented when a new item stack is added (e.g., when allowMultipleStacks creates a new slot) and decremented when an item set is fully consumed or deleted. Cannot exceed currentInventoryMaxCapacity. currentInventoryMaxCapacity int  1 ~ 2147483646 Maximum Capacity The current maximum number of inventory slots available to this user. Initialized from the inventory model’s initialCapacity and can be expanded up to the model’s maxCapacity through acquire actions or direct API calls. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ItemSet Item Set Item Set represents the possessions stored in the game player’s inventory. Item Set holds the Inventory Model name, Item Model name, quantity held, expiration time, and other details. Details  itemSetId string * ~ 1024 chars Item Set A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. count long  1 ~ 9223372036854775805 Quantity in Possession The number of items in this stack. Ranges from 1 to the item model’s stacking limit. When items are acquired, this count increases up to the stacking limit; when consumed, it decreases. If count reaches 0, the item set is deleted and the inventory slot is freed. referenceOf List [] 0 ~ 24 items List of References The external references registered on this item set. Used to track which systems are using this item (e.g., equipped as weapon, assigned to formation). Up to 24 references per item set. sortValue int  0 ~ 2147483646 Display Order A numeric value copied from the item model’s sortValue, used to sort item sets within the inventory for display purposes. Lower values are displayed first. expiresAt long 0 Expiration time Unix time, milliseconds createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server ReferenceOf Reference of Possessions Represents an external reference registered on an item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with active references are protected from consumption or deletion, preventing items in use from being accidentally removed. Details  referenceOfId string * ~ 1024 chars Reference A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Name Identifying the Item Set The UUID name of the item set that this reference is attached to. Used to identify which specific item stack within the inventory is being referenced by an external system. SimpleInventory Simple Inventory Simple inventory is like a bag that stores Simple Items owned by game players. Simple inventory does not have functions such as a cap on the number of items possessed or the capacity of the inventory, but it can increase or decrease multiple items at once. Details  inventoryId string * ~ 1024 chars Simple Inventory A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server inventoryName string  ~ 128 chars Simple Inventory Model Name The name of the simple inventory model that defines the item types for this inventory. Links the user’s simple inventory instance to its model definition. userId string  ~ 128 chars User ID simpleItems List [] 0 ~ 1000 items List of Simple Items All item possessions stored in this simple inventory. Multiple items can be acquired or consumed in a single batch operation. Up to 1000 items per simple inventory. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SimpleItem Simple Item Simple Item represents a possession stored in the game player’s inventory. Simple Item has a model name and the quantity possessed. Details  itemId string * ~ 1024 chars Simple Item A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  0 ~ 9223372036854775805 Quantity in Possession The number of this item type held by the user. Unlike standard inventory items, simple items have no stacking limit and the count can be any value within the int64 range. Can be increased or decreased through batch operations along with other simple items. revision long 0 0 ~ 9223372036854775805 Revision BigInventory Big Inventory Big inventory is like a bag that stores huge items owned by the game player. Big inventory is an inventory that can hold a quantity of items beyond the int64 range. Details  inventoryId string * ~ 1024 chars Big Inventory A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server inventoryName string  ~ 128 chars Big Inventory Model Name The name of the big inventory model that defines the item types for this inventory. Links the user’s big inventory instance to its model definition. userId string  ~ 128 chars User ID bigItems List 0 ~ 1000 items List of Big Items All big item possessions stored in this big inventory. Each item holds its quantity as a big decimal integer string. Up to 1000 items per big inventory. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server BigItem Big Item Big item represents possessions stored in the game player’s Big Inventory. Big Items can hold quantities beyond the range of int64. Details  itemId string * ~ 1024 chars Big Item A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. count string  ~ 1024 chars Quantity in possession Integer value strings up to 1024 digits createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision InventoryModel Inventory Model Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity. Details  inventoryModelId string * ~ 1024 chars Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Inventory Model name Inventory 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool? false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. itemModels List [] 1 ~ 1000 items List of Item Models The item types that can be stored in this inventory. Each item model defines the stacking and acquisition behavior for one type of item. Up to 1000 item models per inventory model. ItemModel Item Model Items can be held in groups within a single inventory slot, such as Potion ×99. This grouping of multiple items into one slot is called “stacking,” and a maximum stack size can be set for each item. The behavior when the stack limit is reached can also be set for each item. Specifically, you can choose one of the following: Add a new inventory slot to allow further acquisition Prevent further acquisition once the limit is reached Details  itemModelId string * ~ 1024 chars Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. SimpleInventoryModel Simple Inventory Model In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation. Details  inventoryModelId string * ~ 1024 chars Simple Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Inventory Model name Simple Inventory 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. simpleItemModels List [] 1 ~ 1000 items List of Simple Item Models The item types that can be stored in this simple inventory. Unlike standard inventory, simple items have no stacking limits or capacity constraints. Up to 1000 item models per simple inventory model. SimpleItemModel Simple Item Model ItemModel allowed setting a maximum stackable quantity, enabling implementation where items exceeding a certain number could be split into multiple stacks. SimpleItem does not have such a function and simply stores the number of items in the possession of the item. Details  itemModelId string * ~ 1024 chars Simple Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Item Model name Simple Item 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. BigInventoryModel Big Inventory Model In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits. Details  inventoryModelId string * ~ 1024 chars Big Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Inventory Model name Big Inventory 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. bigItemModels List [] 1 ~ 1000 items List of Big Item Models The item types that can be stored in this big inventory. Each big item model can hold quantities represented as integer strings up to 1024 digits. Up to 1000 item models per big inventory model. BigItemModel Big Item Model The Big Item Model defines items stored in a Big Inventory Model. Big Items can hold quantities that exceed the range of int64. Details  itemModelId string * ~ 1024 chars Big Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Item Model name Big Item 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. AcquireCount Acquisition quantity of Simple Item Details  itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  1 ~ 9223372036854775805 Acquisition quantity ConsumeCount Consumption quantity of Simple Item Details  itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  1 ~ 9223372036854775805 Consumption quantity HeldCount Quantity of Simple Items in possession Details  itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. count long  0 ~ 9223372036854775805 Number of items held CurrentItemModelMaster Currently active Item Model master data This master data defines the Item Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Inventory Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data InventoryModelMaster Inventory Model Master Inventory Model Master is data used to edit and manage Inventory Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Inventory Model actually referenced by the game. Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity. Details  inventoryModelId string * ~ 1024 chars Inventory Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Inventory Model name Inventory 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. description string ~ 1024 chars Description initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ItemModelMaster Item Model Master Item Model Master is data used to edit and manage Item Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Item Model actually referenced by the game. Items can be held in groups within a single inventory slot, such as Potion ×99. This grouping of multiple items into one slot is called “stacking,” and a maximum stack size can be set for each item. The behavior when the stack limit is reached can also be set for each item. Specifically, you can choose one of the following: Add a new inventory slot to allow further acquisition Prevent further acquisition once the limit is reached Details  itemModelId string * ~ 1024 chars Item Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that this item belongs to. Determines which inventory bag this item type can be stored in and associates it with the inventory’s capacity and protection settings. name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SimpleInventoryModelMaster Simple Inventory Model Master Simple Inventory Model Master is data used to edit and manage Simple Inventory Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Simple Inventory Model actually referenced by the game. In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation. Details  inventoryModelId string * ~ 1024 chars Simple Inventory Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Inventory Model name Simple Inventory 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. description string ~ 1024 chars Description createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SimpleItemModelMaster Simple Item Model Master Simple Item Model Master is data used to edit and manage Simple Item Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Simple Item Model actually referenced by the game. ItemModel allowed setting a maximum stackable quantity, enabling implementation where items exceeding a certain number could be split into multiple stacks. Simple Item does not have such a function and simply stores the number of items in the possession of the item. Details  itemModelId string * ~ 1024 chars Simple Item Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BigInventoryModelMaster Big Inventory Model Master Big Inventory Model Master is data used to edit and manage Big Inventory Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Big Inventory Model actually referenced by the game. In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits. Details  inventoryModelId string * ~ 1024 chars Big Inventory Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Inventory Model name Big Inventory 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. description string ~ 1024 chars Description createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BigItemModelMaster Big Item Model Master Big Item Model Master is data used to edit and manage Big Item Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Big Item Model actually referenced by the game. The Big Item Model defines items that are stored in a Big Inventory Model. Big Items can hold quantities that exceed the range of int64. Details  itemModelId string * ~ 1024 chars Big Item Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new inventory namespace with the specified settings. You can configure GS2-Script triggers for item acquisition (acquireScript), overflow handling (overflowScript), and consumption (consumeScript) for standard inventory items. Separate script settings are available for simple items (simpleItemAcquireScript, simpleItemConsumeScript) and big items (bigItemAcquireScript, bigItemConsumeScript). The overflow script is invoked when acquiring items would exceed the inventory capacity, enabling forwarding to systems like GS2-Inbox. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configures distributed transaction processing for inventory operations such as acquiring and consuming items. Supports auto-run mode for seamless execution, atomic commit for consistent multi-resource operations, and async processing for large-scale reward distribution. acquireScript ScriptSetting Script setting to be executed when an Items is acquired Script Trigger Reference - acquire overflowScript ScriptSetting Script to execute when unable to obtain due to reaching the acquisition limit Script Trigger Reference - overflowDone consumeScript ScriptSetting Script to run when consuming Items Script Trigger Reference - consume simpleItemAcquireScript ScriptSetting Script setting to be executed when acquiring Simple Items Script Trigger Reference - simpleItemAcquire simpleItemConsumeScript ScriptSetting Script to run when consuming Simple Items Script Trigger Reference - simpleItemConsume bigItemAcquireScript ScriptSetting Script setting to be executed when acquiring Big Items Script Trigger Reference - bigItemAcquire bigItemConsumeScript ScriptSetting Script to run when consuming Big Items Script Trigger Reference - bigItemConsume logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of inventory operations. Useful for tracking item acquisition, consumption, and capacity changes for debugging and analytics. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the settings of the specified inventory namespace. You can modify GS2-Script triggers for item acquisition, overflow handling, and consumption for standard, simple, and big items. Changes to script settings take effect immediately for subsequent operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configures distributed transaction processing for inventory operations such as acquiring and consuming items. Supports auto-run mode for seamless execution, atomic commit for consistent multi-resource operations, and async processing for large-scale reward distribution. acquireScript ScriptSetting Script setting to be executed when an Items is acquired Script Trigger Reference - acquire overflowScript ScriptSetting Script to execute when unable to obtain due to reaching the acquisition limit Script Trigger Reference - overflowDone consumeScript ScriptSetting Script to run when consuming Items Script Trigger Reference - consume simpleItemAcquireScript ScriptSetting Script setting to be executed when acquiring Simple Items Script Trigger Reference - simpleItemAcquire simpleItemConsumeScript ScriptSetting Script to run when consuming Simple Items Script Trigger Reference - simpleItemConsume bigItemAcquireScript ScriptSetting Script setting to be executed when acquiring Big Items Script Trigger Reference - bigItemAcquire bigItemConsumeScript ScriptSetting Script to run when consuming Big Items Script Trigger Reference - bigItemConsume logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of inventory operations. Useful for tracking item acquisition, consumption, and capacity changes for debugging and analytics. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data dump operation. The dump includes all inventory data, item sets, simple items, and big items owned by the user. When complete, returns a URL to download the exported data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data cleaning operation. The cleaning removes all inventory data, item sets, simple items, and big items owned by the user across all namespaces in this service. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data import operation. The import restores inventory data, item sets, simple items, and big items from previously exported data. When complete, returns a URL to download the import log. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeInventories Get a list of Inventories Retrieves a paginated list of the requesting user’s inventories. Each inventory tracks the current capacity (number of item slots) for a specific inventory model. Inventories are automatically created when a user first acquires an item, with the initial capacity set by the inventory model’s initialCapacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Inventories nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeInventoriesByUserId Get a list of Inventories by specifying a user ID Retrieves a paginated list of inventories for the specified user. Each inventory tracks the current capacity (number of item slots) for a specific inventory model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Inventories nextPageToken string Page token to retrieve the rest of the listing Implementation Example getInventory Get Inventory Retrieves the requesting user’s inventory for the specified inventory model, including the current capacity. If the user has never acquired an item in this inventory, no data will be returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. accessToken string  ~ 128 chars Access token Result Type Description item Inventory Inventory Implementation Example getInventoryByUserId Get Inventory by specifying a user ID Retrieves the specified user’s inventory for the given inventory model, including the current capacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Inventory Inventory Implementation Example addCapacityByUserId Add inventory capacity size by specifying a user ID Incrementally increases the user’s inventory capacity by the specified amount. The resulting capacity cannot exceed the inventory model’s maxCapacity. If the inventory does not yet exist, it is automatically created with initialCapacity before adding the specified value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID addCapacityValue int  1 ~ 2147483646 Capacity size to be added timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Inventory Inventory after capacity addition Implementation Example setCapacityByUserId Set inventory capacity size by specifying a user ID Sets the user’s inventory capacity to the specified absolute value. Returns both the inventory state before and after the update, allowing you to compare old and new capacity values. The new capacity value cannot exceed the inventory model’s maxCapacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID newCapacityValue int  1 ~ 2147483646 New maximum capacity for inventory timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Inventory Inventory after update old Inventory Inventory before update Implementation Example deleteInventoryByUserId Delete inventory Deletes the specified user’s inventory along with all associated item sets. This operation permanently removes the inventory and all items stored within it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Inventory Inventory Implementation Example verifyInventoryCurrentMaxCapacity Verify current max inventory capacity Verifies that the user’s current maximum inventory capacity satisfies the specified condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. The verification uses the buffed capacity value (reflecting any active buff effects from GS2-Buff), not the raw stored value. If the condition is not met, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Current max inventory capacity is less than the specified value “lessEqual” Current max inventory capacity is less than or equal to the specified value “greater” Current max inventory capacity is greater than the specified value “greaterEqual” Current max inventory capacity is greater than or equal to the specified value “equal” Current max inventory capacity is equal to the specified value “notEqual” Current max inventory capacity is not equal to the specified value currentInventoryMaxCapacity int  0 ~ 2147483646 Current max inventory capacity multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Inventory Inventory Implementation Example verifyInventoryCurrentMaxCapacityByUserId Verify current max inventory capacity by specifying a user ID Verifies that the specified user’s current maximum inventory capacity satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. The verification uses the buffed capacity value (reflecting any active buff effects from GS2-Buff). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Current max inventory capacity is less than the specified value “lessEqual” Current max inventory capacity is less than or equal to the specified value “greater” Current max inventory capacity is greater than the specified value “greaterEqual” Current max inventory capacity is greater than or equal to the specified value “equal” Current max inventory capacity is equal to the specified value “notEqual” Current max inventory capacity is not equal to the specified value currentInventoryMaxCapacity int  0 ~ 2147483646 Current max inventory capacity multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Inventory Inventory Implementation Example describeItemSets Get a list of Item Sets Retrieves a paginated list of the requesting user’s item sets within the specified inventory. Each item set represents a stack of items with a specific quantity, optional expiration time, and optional references. When an item model allows multiple stacks, the same item type may appear as multiple item set entries with different quantities and expiration times. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Item Sets nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeItemSetsByUserId Get a list of Item Sets by specifying a user ID Retrieves a paginated list of the specified user’s item sets within the given inventory. Each item set represents a stack of items with a specific quantity, optional expiration time, and optional references. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Item Sets nextPageToken string Page token to retrieve the rest of the listing Implementation Example getItemSet Get Item Set Retrieves the item sets for the specified item within the requesting user’s inventory. An optional itemSetName can filter to a specific stack; without it, all stacks for the item are returned. Also returns the associated item model and inventory information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string ~ 36 chars Name identifying the item set Result Type Description items List List of Item Sets itemModel ItemModel Item Model inventory Inventory inventory Implementation Example getItemSetByUserId Get Item Set by specifying the user ID Retrieves the item sets for the specified item within the given user’s inventory. An optional itemSetName can filter to a specific stack; without it, all stacks for the item are returned. Also returns the associated item model and inventory information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string ~ 36 chars Name identifying the item set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Item Sets itemModel ItemModel Item Model inventory Inventory inventory Implementation Example getItemWithSignature Get Item Set along with the signature Retrieves the item sets with a cryptographic signature that can be used to verify the data’s authenticity. The signature is generated using the specified encryption key, allowing external systems to validate that the item data has not been tampered with. Useful for server-authoritative validation scenarios where item possession must be verified by a third party. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string ~ 36 chars Name identifying the Item Set keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description items List List of Item Sets itemModel ItemModel Item Model inventory Inventory Inventory body string Item Set Information for Signature Subject signature string Signature Implementation Example getItemWithSignatureByUserId Get Item Set with signature by specifying the user ID Retrieves the item sets with a cryptographic signature for the specified user. The signature is generated using the specified encryption key for external authenticity verification. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string ~ 36 chars Name identifying the Item Set keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Item Sets itemModel ItemModel Item Model inventory Inventory Inventory body string Item Set Information for Signature Subject signature string Signature Implementation Example acquireItemSetByUserId Acquire Item Sets by specifying the user ID Adds items to the user’s inventory. If an existing item set has room (below the stacking limit), items are added to it; otherwise, a new item set is created if multiple stacks are allowed. An optional expiresAt can set an expiration time for newly created item sets. Items with an expiration time already in the past are treated as empty. When createNewItemSet is true, a new item set is always created even if existing sets have room. If the total quantity exceeds the inventory capacity, the overflow count is returned, and overflow items may be forwarded to GS2-Inbox depending on the namespace configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. userId string  ~ 128 chars User ID acquireCount long  1 ~ 9223372036854775805 Acquisition quantity expiresAt long 0 Expiration time Unix time, milliseconds createNewItemSet bool false Even if there is room in an existing Item Set, you can create a new Item Set itemSetName string ~ 36 chars Name identifying the Item Set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Item Set after addition itemModel ItemModel Item Model inventory Inventory Inventory overflowCount long Quantity of items transferred to GS2-Inbox that were not received beyond the possession limit Implementation Example acquireItemSetWithGradeByUserId Acquire one Item Set while setting the grade to GS2-Grade by specifying the user ID Acquires exactly one item and simultaneously sets a grade value on it via GS2-Grade. This is used for items that have a quality/rank system where each individual item has a different grade value (e.g., equipment with varying stats). A new item set is always created (createNewItemSet behavior), and the grade is set through GS2-Grade’s SetGradeByUserId after the item acquisition. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. userId string  ~ 128 chars User ID gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeValue long  1 ~ 9223372036854775805 Grade value to set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ItemSet Item Set after addition status Status Grade status set itemModel ItemModel Item Model inventory Inventory Inventory overflowCount long Quantity of items transferred to GS2-Inbox that were not received beyond the possession limit Implementation Example consumeItemSet Consume Item Sets Reduces the quantity of the specified item in the requesting user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items to consume the requested amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. consumeCount long  1 ~ 9223372036854775805 Consumption quantity itemSetName string ~ 36 chars Name identifying the Item Set Result Type Description items List List of Item Sets per post-consumption itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example consumeItemSetByUserId Consume Item Sets by specifying the user ID Reduces the quantity of the specified item in the given user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. consumeCount long  1 ~ 9223372036854775805 Consumption quantity itemSetName string ~ 36 chars Name identifying the Item Set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Item Sets per post-consumption itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example deleteItemSetByUserId Delete Item Set Permanently deletes the specified item from the user’s inventory. If itemSetName is specified, only that specific stack is deleted. Without it, all stacks of the item type are deleted. Unlike consume, this operation does not require a specific quantity and removes the entire item set regardless of its count. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string ~ 36 chars Name identifying the item set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of deleted Item Sets itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example verifyItemSet Verify the quantity of Item Sets in possession Verifies that the requesting user’s total item count satisfies the specified condition. The count is summed across all item sets of the specified item type. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. If the condition is not met, an error is returned with the inverted condition name (e.g., a “less” check failure returns a “greaterEqual” error). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value itemSetName string ~ 36 chars Name identifying the item set count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description items List List of deleted Item Sets Implementation Example verifyItemSetByUserId Verify the quantity of Item Sets in possession by specifying the user ID Verifies that the specified user’s total item count satisfies the given condition. The count is summed across all item sets of the specified item type. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value itemSetName string ~ 36 chars Name identifying the item set count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of deleted Item Sets Implementation Example describeReferenceOf Get a list of references Retrieves the list of reference strings registered on a specific item set for the requesting user. References are used to associate item sets with external entities (e.g., equipment slots), and when protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. Result Type Description items List List of References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example describeReferenceOfByUserId Get a list of references by specifying a user ID Retrieves the list of reference strings registered on a specific item set for the specified user. References are used to associate item sets with external entities (e.g., equipment slots), and when protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example getReferenceOf Get reference source Retrieves a specific reference string registered on an item set for the requesting user. Also returns the associated item set, item model, and inventory data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. Result Type Description item string References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example getReferenceOfByUserId Get reference source by specifying a user ID Retrieves a specific reference string registered on an item set for the specified user. Also returns the associated item set, item model, and inventory data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item string References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example verifyReferenceOf Verify the reference source Verifies the state of a reference on an item set for the requesting user. Supports four verification types: not_entry (reference not yet registered), already_entry (reference already registered), empty (no references at all), and not_empty (at least one reference exists). If the condition is not met, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. verifyType string (enum) enum {   “not_entry”,   “already_entry”,   “empty”,   “not_empty” }  Type of verification Definition Description “not_entry” That the specified reference is not yet registered. “already_entry” That the specified reference is already registered. “empty” The number of elements registered as references is zero. “not_empty” At least one element registered as a reference source Result Type Description item string References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example verifyReferenceOfByUserId Verify the reference source by specifying the user ID Verifies the state of a reference on an item set for the specified user. Supports four verification types: not_entry (reference not yet registered), already_entry (reference already registered), empty (no references at all), and not_empty (at least one reference exists). If the condition is not met, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. verifyType string (enum) enum {   “not_entry”,   “already_entry”,   “empty”,   “not_empty” }  Type of verification Definition Description “not_entry” That the specified reference is not yet registered. “already_entry” That the specified reference is already registered. “empty” The number of elements registered as references is zero. “not_empty” At least one element registered as a reference source timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item string References for this possession itemSet ItemSet Item Set itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example addReferenceOf Add a reference Registers a reference string on the specified item set for the requesting user. References associate the item set with an external entity (e.g., an equipment slot or character). When protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted, preventing accidental loss of equipped items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. Result Type Description item string References for this possession itemSet ItemSet Item Set after addition of reference source itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example addReferenceOfByUserId Add a reference by specifying a user ID Registers a reference string on the specified item set for the specified user. References associate the item set with an external entity (e.g., an equipment slot or character). When protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted, preventing accidental loss of equipped items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item string References for this possession itemSet ItemSet Item Set after addition of reference source itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example deleteReferenceOf Delete References Removes a specific reference string from the specified item set for the requesting user. After removal, if protectReferencedItem is enabled and no other references remain, the item becomes eligible for consumption or deletion again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. Result Type Description item string References for this possession itemSet ItemSet Item Set after deleting the reference source itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example deleteReferenceOfByUserId Delete the reference source by specifying the user ID Removes a specific reference string from the specified item set for the specified user. After removal, if protectReferencedItem is enabled and no other references remain, the item becomes eligible for consumption or deletion again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item string References for this possession itemSet ItemSet Item Set after deleting the reference source itemModel ItemModel Item Model inventory Inventory Inventory Implementation Example describeSimpleItems Get a list of Simple Items Retrieves a paginated list of the requesting user’s simple items within the specified simple inventory. Each simple item tracks a single count value for an item type, without stacking, expiration, or references. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Simple Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSimpleItemsByUserId Get a list of Simple Items by specifying a user ID Retrieves a paginated list of the specified user’s simple items within the given simple inventory. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Simple Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSimpleItem Get a Simple Item Retrieves the requesting user’s simple item with the specified name, including its current count and the associated item model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. Result Type Description item SimpleItem Simple Item itemModel SimpleItemModel Simple Item Model Implementation Example getSimpleItemByUserId Get a Simple Item by specifying a user ID Retrieves the specified user’s simple item with the given name, including its current count and the associated item model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SimpleItem Simple Item itemModel SimpleItemModel Simple Item Model Implementation Example getSimpleItemWithSignature Get a Simple Item along with the signature Retrieves the simple item with a cryptographic signature for authenticity verification. The signature is generated using the specified encryption key, allowing external systems to validate the item data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item SimpleItem Simple Item simpleItemModel SimpleItemModel Simple Item Model body string Simple Item Information for Signature Subject signature string Signature Implementation Example getSimpleItemWithSignatureByUserId Get a Simple Item with signature by specifying the user ID Retrieves the specified user’s simple item with a cryptographic signature for external authenticity verification. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SimpleItem Simple Item simpleItemModel SimpleItemModel Simple Item Model body string Simple Item Information for Signature Subject signature string Signature Implementation Example acquireSimpleItemsByUserId Acquire Simple Items by specifying a user ID Adds items to the user’s simple inventory using a batch of acquire counts. Multiple items can be acquired in a single atomic operation — the acquireCounts array specifies the item name and quantity for each item to acquire. Unlike regular item sets, simple items have no capacity limits, stacking limits, or expiration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID acquireCounts List  1 ~ 100 items List of acquisition quantities for Simple Items timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Simple Items after addition Implementation Example consumeSimpleItems Consume Simple Items Reduces the quantity of items in the requesting user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails. Returns an Insufficient error if the user does not have enough of any specified item. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items Result Type Description items List List of Simple Items per post-consumption Implementation Example consumeSimpleItemsByUserId Consume Simple Items by specifying a user ID Reduces the quantity of items in the specified user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Simple Items per post-consumption Implementation Example setSimpleItemsByUserId Set the quantity of simple items by specifying a user ID Sets the absolute quantities of multiple simple items in a single atomic operation. The counts array specifies the item name and target quantity for each item. This overwrites the current quantities entirely, unlike acquire/consume which are relative operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID counts List  1 ~ 100 items List of quantity of Simple Items in possession timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Simple Items after update Implementation Example deleteSimpleItemsByUserId Delete simple item possession quantities Deletes all simple items in the specified simple inventory for the given user. This permanently removes all item data within the inventory. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example verifySimpleItem Verify the quantity of possessions in simple items Verifies that the requesting user’s simple item count satisfies the specified condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. If the condition is not met, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item SimpleItem Quantity of simple items Implementation Example verifySimpleItemByUserId Verify the quantity of possessions in simple items by specifying a user ID Verifies that the specified user’s simple item count satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SimpleItem Quantity of simple items Implementation Example describeBigItems Get a list of Big Items Retrieves a paginated list of big items owned by the requesting user in the specified big inventory. Big items use string-based arbitrary-precision counts, suitable for values that exceed standard integer limits. Items that have never been acquired will not appear in the results. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Quantity of Big Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeBigItemsByUserId Get a list of Big Items by specifying a user ID Retrieves a paginated list of big items owned by the specified user in the specified big inventory. Big items use string-based arbitrary-precision counts, suitable for values that exceed standard integer limits. Items that have never been acquired will not appear in the results. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Quantity of Big Items nextPageToken string Page token to retrieve the rest of the listing Implementation Example getBigItem Get a Big Item Retrieves a specific big item and its string-based arbitrary-precision count for the requesting user. The response includes both the big item data and its associated big item model definition. If the item has never been acquired, no data will be returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. Result Type Description item BigItem Big Item itemModel BigItemModel Big Item Model Implementation Example getBigItemByUserId Get a Big Item by specifying the user ID Retrieves a specific big item and its string-based arbitrary-precision count for the specified user. The response includes both the big item data and its associated big item model definition. If the item has never been acquired, no data will be returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item itemModel BigItemModel Big Item Model Implementation Example acquireBigItemByUserId Acquire Big Item by specifying a user ID Adds the specified quantity to the user’s big item count using arbitrary-precision arithmetic. The acquireCount must be a valid integer string up to 1024 digits; an invalid format will result in an error. If the item does not yet exist, it will be automatically created. A GS2-Script can be configured to execute custom logic when big items are acquired via the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). acquireCount string  ~ 1024 chars Acquisition quantity for a Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item after addition Implementation Example consumeBigItem Consume Big Items Subtracts the specified quantity from the requesting user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits Result Type Description item BigItem Big Item per post-consumption Implementation Example consumeBigItemByUserId Consume Big Items by specifying a user ID Subtracts the specified quantity from the specified user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item per post-consumption Implementation Example setBigItemByUserId Set the Big Item by specifying a user ID Sets the big item count to the specified absolute value, replacing the current count entirely. The count must be a valid integer string up to 1024 digits. If the item does not yet exist, it will be automatically created. Unlike acquire/consume which perform relative operations, this sets the exact value directly. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). count string  ~ 1024 chars Quantity of Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item after update Implementation Example deleteBigItemByUserId Delete Big Item Permanently deletes the specified big item data for the user. The item record is completely removed regardless of its current count. This operation cannot be undone. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item per post-consumption Implementation Example verifyBigItem Verify possession quantity of big items Verifies that the requesting user’s big item count satisfies the specified condition. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. The comparison is performed using arbitrary-precision arithmetic on string-based counts. If the condition is not met, an error is returned; if met, the request succeeds. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count string  ~ 1024 chars Quantity in possession Integer value strings up to 1024 digits multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item BigItem Big Item after update Implementation Example verifyBigItemByUserId Verify possession quantity of Big Items by specifying a user ID Verifies that the specified user’s big item count satisfies the specified condition. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. The comparison is performed using arbitrary-precision arithmetic on string-based counts. If the condition is not met, an error is returned; if met, the request succeeds. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count string  ~ 1024 chars Quantity in possession Integer value strings up to 1024 digits multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BigItem Big Item after update Implementation Example describeInventoryModels Get a list of Inventory Models Retrieves the list of currently active inventory models in the namespace. These are the models activated through the current master data update process, defining the capacity settings (initialCapacity, maxCapacity) and item protection rules (protectReferencedItem) for each inventory type. Each inventory model contains its associated item models, which define stacking limits and sort order for items within that inventory. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Inventory Models Implementation Example getInventoryModel Get Inventory Model Retrieves a specific active inventory model including its full configuration: initial and maximum capacity, item protection settings, and all associated item models. The item models define how items are stored within this inventory, including stacking limits, multi-stack allowance, and sort values. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item InventoryModel Inventory Model Implementation Example describeItemModels Get a list of Item Models Retrieves the list of currently active item models belonging to the specified inventory model. Each item model defines the stacking limit (maximum count per stack), whether multiple stacks are allowed, and the sort value for display ordering. These are the models activated through the current master data update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Item Model Implementation Example getItemModel Get Item Model Retrieves a specific active item model, including its stacking limit, multi-stack allowance, sort value, and any other configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ItemModel Implementation Example describeSimpleInventoryModels Get a list of Simple Inventory Models Retrieves the list of currently active simple inventory models in the namespace. Simple inventory models provide a streamlined item management system without capacity limits, expiration, or references — items are tracked as simple name-count pairs. Each model contains its associated simple item models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Simple Inventory Models Implementation Example getSimpleInventoryModel Get Simple Inventory Model Retrieves a specific active simple inventory model including its associated simple item models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleInventoryModel Simple Inventory Model Implementation Example describeSimpleItemModels Get a list of Simple Item Models Retrieves the list of currently active simple item models belonging to the specified simple inventory model. Simple item models define item types that are tracked as simple name-count pairs without stacking limits, expiration, or references. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Simple Item Model Implementation Example getSimpleItemModel Get Simple Item Model Retrieves a specific active simple item model and its configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleItemModel Implementation Example describeBigInventoryModels Get a list of Big Inventory Models Retrieves the list of currently active big inventory models in the namespace. Big inventory models support arbitrary-precision item counts using string-based numbers, suitable for games that need extremely large quantities beyond standard integer limits. Each model contains its associated big item models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Big Inventory Models Implementation Example getBigInventoryModel Get Big Inventory Model Retrieves a specific active big inventory model including its associated big item models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigInventoryModel Big Inventory Model Implementation Example describeBigItemModels Get a list of Big Item Models Retrieves the list of currently active big item models belonging to the specified big inventory model. Big item models define item types that use string-based arbitrary-precision counts. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Big Item Model Implementation Example getBigItemModel Get Big Item Model Retrieves a specific active big item model and its configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigItemModel Implementation Example exportMaster Export Item Model Master in a master data format that can be activated Exports the current set of inventory model masters, item model masters, simple inventory/item model masters, and big inventory/item model masters from the namespace as a JSON document. The exported data can be used as input for the update master data API to activate changes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentItemModelMaster Item Model Master that can be activated Implementation Example getCurrentItemModelMaster Get currently active Item Model master data Retrieves the master data that was last activated in the namespace. This includes all inventory models (standard, simple, and big) and their associated item models that are currently in use by the service. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentItemModelMaster Currently active Item Model master data Implementation Example preUpdateCurrentItemModelMaster Update currently active Item Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentItemModelMaster Update currently active Item Model master data Activates new master data to replace the currently active inventory and item model definitions. Supports two modes: ‘direct’ for inline data (suitable for data under 1MB), and ‘preUpload’ for data that was uploaded via the pre-update API. After activation, all inventory operations will use the new model definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentItemModelMaster Updated master data of the currently active Item Models Implementation Example updateCurrentItemModelMasterFromGitHub Update currently active Item Model master data from GitHub Fetches master data from a specified GitHub repository and activates it. The checkout setting specifies the repository, branch/tag, and file path to retrieve. Template variables in the master data are replaced with their configured values during activation. This enables version-controlled master data management through Git workflows. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentItemModelMaster Updated master data of the currently active Item Models Implementation Example describeInventoryModelMasters Get a list of Inventory Model Masters Retrieves a paginated list of editable inventory model masters in the namespace. These are the draft definitions that can be modified before activation. Each master defines the capacity settings (initialCapacity, maxCapacity) and item protection rules for an inventory type. Supports optional name prefix filtering for targeted searches. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Inventory Model name prefix 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 List of Inventory Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createInventoryModelMaster Create a new Inventory Model Master Creates an editable inventory model master that defines a new inventory type. Key settings include initialCapacity (the starting number of item slots for new users), maxCapacity (the upper limit for capacity expansion), and protectReferencedItem (when enabled, prevents consumption of items that have active references). The created master must be activated through the current master data update process to become available to users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. Result Type Description item InventoryModelMaster Created Inventory Model Master Implementation Example getInventoryModelMaster Get Inventory Model Master Retrieves the full configuration of a specific editable inventory model master, including its capacity settings, metadata, and item protection rules. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item InventoryModelMaster Inventory Model Master Implementation Example updateInventoryModelMaster Update Inventory Model Master Updates the properties of an existing inventory model master, including capacity settings (initialCapacity, maxCapacity), metadata, and protectReferencedItem. Changes do not take effect until the master data is re-activated through the current master data update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. Result Type Description item InventoryModelMaster Inventory Model Master updated Implementation Example deleteInventoryModelMaster Delete Inventory Model Master Deletes the specified inventory model master. The deletion does not affect the currently active model until the master data is re-activated. Existing user inventories and items associated with this model are not automatically deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item InventoryModelMaster Inventory Model Master deleted Implementation Example describeItemModelMasters Get a list of Item Model Masters Retrieves a paginated list of editable item model masters belonging to the specified inventory model master. These are the draft definitions that can be modified before activation, defining stacking limits, multi-stack allowance, and sort values for items within the inventory. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory 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 List of Item Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createItemModelMaster Create a new Item Model Master Creates an editable item model master that defines a new item type within the specified inventory. Key settings include stackingLimit (maximum quantity per stack), allowMultipleStacks (whether the same item can occupy multiple inventory slots), and sortValue (display ordering priority). When allowMultipleStacks is enabled, acquiring items beyond the stacking limit creates additional ItemSet entries rather than failing. The created master must be activated through the current master data update process to become available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that this item belongs to. Determines which inventory bag this item type can be stored in and associates it with the inventory’s capacity and protection settings. name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. Result Type Description item ItemModelMaster Item Model Master created Implementation Example getItemModelMaster Get Item Model Master Retrieves the full configuration of a specific editable item model master, including its stacking limit, multi-stack allowance, sort value, and metadata. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ItemModelMaster Item Model Master Implementation Example updateItemModelMaster Update Item Model Master Updates the properties of an existing item model master, including stacking limit, multi-stack allowance, sort value, and metadata. Changes do not take effect until the master data is re-activated through the current master data update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. Result Type Description item ItemModelMaster Item Model Master updated Implementation Example deleteItemModelMaster Delete Item Model Master Deletes the specified item model master. The deletion does not affect the currently active model until the master data is re-activated. Existing user items associated with this model are not automatically deleted. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ItemModelMaster Item Model Master deleted Implementation Example describeSimpleInventoryModelMasters Get a list of Simple Inventory Model Masters Retrieves a paginated list of editable simple inventory model masters in the namespace. These are the draft definitions that can be modified before activation through the master data update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Simple Inventory Model name prefix 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 List of Simple Inventory Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSimpleInventoryModelMaster Create a new Simple Inventory Model Master Creates an editable simple inventory model master. Unlike regular inventory models, simple inventory models do not have capacity limits, item expiration, or reference management. The created master must be activated through the current master data update process to become available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item SimpleInventoryModelMaster Created Simple Inventory Model Master created Implementation Example getSimpleInventoryModelMaster Get Simple Inventory Model Master Retrieves the full configuration of a specific editable simple inventory model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleInventoryModelMaster Simple Inventory Model Master Implementation Example updateSimpleInventoryModelMaster Update Simple Inventory Model Master Updates the properties of an existing simple inventory model master. Changes do not take effect until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item SimpleInventoryModelMaster Simple Inventory Model Master updated Implementation Example deleteSimpleInventoryModelMaster Delete Simple Inventory Model Master Deletes the specified simple inventory model master. The deletion does not affect the currently active model until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleInventoryModelMaster Simple Inventory Model Master deleted Implementation Example describeSimpleItemModelMasters Get a list of Simple Item Model Masters Retrieves a paginated list of editable simple item model masters belonging to the specified simple inventory model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Simple Item Model name prefix 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 List of Simple Item Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSimpleItemModelMaster Create a new Simple Item Model Master Creates an editable simple item model master that defines a new item type within the specified simple inventory. The created master must be activated through the current master data update process to become available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item SimpleItemModelMaster Item Model Master created Implementation Example getSimpleItemModelMaster Get Simple Item Model Master Retrieves the full configuration of a specific editable simple item model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleItemModelMaster Simple Item Model Master Implementation Example updateSimpleItemModelMaster Update Simple Item Model Master Updates the properties of an existing simple item model master. Changes do not take effect until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item SimpleItemModelMaster Simple Item Model Master updated Implementation Example deleteSimpleItemModelMaster Delete Simple Item Model Master Deletes the specified simple item model master. The deletion does not affect the currently active model until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model name Simple Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SimpleItemModelMaster Simple Item Model Master deleted Implementation Example describeBigInventoryModelMasters Get a list of Big Inventory Model Masters Retrieves a paginated list of editable big inventory model masters in the namespace. These are the draft definitions for inventory types that use arbitrary-precision item counts. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Big Inventory Model name prefix 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 List of Big Inventory Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createBigInventoryModelMaster Create a new Big Inventory Model Master Creates an editable big inventory model master for arbitrary-precision item management. The created master must be activated through the current master data update process to become available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item BigInventoryModelMaster Created Big Inventory Model Master Implementation Example getBigInventoryModelMaster Get Big Inventory Model Master Retrieves the full configuration of a specific editable big inventory model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigInventoryModelMaster Big Inventory Model Master Implementation Example updateBigInventoryModelMaster Update Big Inventory Model Master Updates the properties of an existing big inventory model master. Changes do not take effect until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item BigInventoryModelMaster Big Inventory Model Master updated Implementation Example deleteBigInventoryModelMaster Delete Big Inventory Model Master Deletes the specified big inventory model master. The deletion does not affect the currently active model until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigInventoryModelMaster Big Inventory Model Master deleted Implementation Example describeBigItemModelMasters Get a list of Big Item Model Masters Retrieves a paginated list of editable big item model masters belonging to the specified big inventory model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Big Item Model name prefix 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 List of Big Item Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createBigItemModelMaster Create a new Big Item Model Master Creates an editable big item model master that defines a new item type with arbitrary-precision counts within the specified big inventory. The created master must be activated through the current master data update process to become available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item BigItemModelMaster Item Model Master created Implementation Example getBigItemModelMaster Get Big Item Model Master Retrieves the full configuration of a specific editable big item model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigItemModelMaster Big Item Model Master Implementation Example updateBigItemModelMaster Update Big Item Model Master Updates the properties of an existing big item model master. Changes do not take effect until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. Result Type Description item BigItemModelMaster Big Item Model Master updated Implementation Example deleteBigItemModelMaster Delete Big Item Model Master Deletes the specified big item model master. The deletion does not affect the currently active model until the master data is re-activated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BigItemModelMaster Big Item Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Inventory SDK for various programming languages\n","title":"GS2-Inventory SDK API Reference","url":"/api_reference/inventory/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing job queue operations. enableAutoRun bool false Whether to automatically execute jobs on the server side When enabled, registered jobs are automatically executed on the server side without requiring the client to poll and run them. When disabled, the client must explicitly call the run API to process jobs, and a pushNotification can be used to notify the client of new jobs. runNotification NotificationSetting  Run Notification Push Notification Setting via GS2-Gateway when a job in the job queue is executed. The notification includes the job result, allowing the client to display rewards or handle errors without additional API calls. pushNotification NotificationSetting !{enableAutoRun} Push Notification Push Notification Setting via GS2-Gateway when a new job is registered in the job queue. Only available when enableAutoRun is disabled. Used to prompt the client to call the run API to process the newly registered job. * Enabled only if enableAutoRun is “false”. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of job queue operations. Useful for tracking job registration, execution, retry, and failure for debugging and analytics. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Job Job A job queue is a mechanism for delaying the execution of a process rather than completing it immediately. For example, when a character is acquired, the process that must be executed immediately is to store the character in the inventory. On the other hand, a process that does not have to be executed immediately is the process of registering the character to the dictionary . By processing tasks that do not need to be executed immediately through a job queue, the system can be made more fault-tolerant. This is because even if the dictionary service is stopped due to some failure, the game can continue without being registered in the dictionary. Even if the process enqueued in the job queue fails, it can be retried after the failure is resolved, resulting in a correct state. GS2 recommends this kind of eventual consistency process, and in various situations, job queues are used for delayed processing. Details  jobId string * ~ 1024 chars Job A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. userId string  ~ 128 chars User ID scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN args string  ~ 5242880 chars Argument The JSON-formatted request parameters to pass to the script when the job is executed. Contains the specific operation details such as action type and target resources. Maximum 5MB. currentRetryCount int 0 0 ~ 100 Current Retry Count The number of times this job has been retried after failure. Incremented each time execution results in a retryable error. When this count reaches maxTryCount, the job is marked as permanently failed. maxTryCount int 3 1 ~ 100 Maximum Number of Attempts The maximum number of times this job can be executed, including the initial attempt and retries. If all attempts fail, the job is abandoned. Default is 3, maximum is 100. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server JobResult Job Execution Results Records the outcome of a single job execution attempt. Each attempt creates a separate JobResult, so a job that is retried multiple times will have multiple results. The statusCode indicates whether the job succeeded or failed. Details  jobResultId string * ~ 1024 chars Job execution result A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server jobId string  ~ 1024 chars Job A unique resource name assigned to all information handled by GS2\" \u003e GRN scriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN args string ~ 5242880 chars Argument The JSON-formatted request parameters that were passed to the script for this execution attempt. tryNumber int  0 ~ 10000 Try Number The sequential attempt number for this execution result, starting from 0. The first attempt is 0, the first retry is 1, and so on. Used to correlate results with specific retry attempts. statusCode int  0 ~ 1000 Status Code The HTTP status code returned by the script execution. A 2xx code indicates success, and other codes indicate failure. Retryable errors may trigger automatic retry if maxTryCount has not been reached. result string  ~ 5242880 chars Response Content The JSON-formatted response body returned by the script execution. Contains the result data on success or error details on failure. Maximum 5MB. tryAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server JobEntry Register Job Represents the parameters for registering a new job to the job queue. Contains the script to execute, the JSON arguments, and the maximum retry count. Used as input when pushing jobs onto the queue. Details  scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN args string “{}” ~ 131072 chars Argument The JSON-formatted request parameters to pass to the script when the job is executed. Defaults to an empty JSON object “{}”. Maximum 128KB. maxTryCount int 3 0 ~ 100 Maximum Number of Attempts The maximum number of times the job can be executed, including the initial attempt and retries. Default is 3, maximum is 100. JobResultBody Job Execution Result Body A lightweight representation of a job execution result, containing the attempt number, status code, response content, and execution timestamp. Details  tryNumber int  1 ~ 10000 Try Number The sequential attempt number for this execution result, starting from 1. Used to identify which retry attempt produced this result. statusCode int  0 ~ 1000 Status Code The HTTP status code returned by the script execution. A 2xx code indicates success, and other codes indicate failure. Retryable errors may trigger automatic retry if maxTryCount has not been reached. result string  ~ 5242880 chars Response Content The JSON-formatted response body returned by the script execution. Contains the result data on success or error details on failure. Maximum 5MB. tryAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new job queue namespace with the specified settings. The enableAutoRun setting controls whether jobs are executed automatically upon registration (true) or queued for manual execution via the Run API (false). You can configure a pushNotification to receive notifications when jobs are added to the queue, and a runNotification to receive notifications when jobs complete execution. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing job queue operations. enableAutoRun bool false Whether to automatically execute jobs on the server side When enabled, registered jobs are automatically executed on the server side without requiring the client to poll and run them. When disabled, the client must explicitly call the run API to process jobs, and a pushNotification can be used to notify the client of new jobs. pushNotification NotificationSetting !{enableAutoRun} Push Notification Push Notification Setting via GS2-Gateway when a new job is registered in the job queue. Only available when enableAutoRun is disabled. Used to prompt the client to call the run API to process the newly registered job. * Enabled only if enableAutoRun is “false” runNotification NotificationSetting  Run Notification Push Notification Setting via GS2-Gateway when a job in the job queue is executed. The notification includes the job result, allowing the client to display rewards or handle errors without additional API calls. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of job queue operations. Useful for tracking job registration, execution, retry, and failure for debugging and analytics. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the settings of the specified job queue namespace. You can modify the enableAutoRun setting to switch between automatic and manual job execution modes, as well as update push and run notification configurations. Changes take effect immediately for subsequent operations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing job queue operations. enableAutoRun bool false Whether to automatically execute jobs on the server side When enabled, registered jobs are automatically executed on the server side without requiring the client to poll and run them. When disabled, the client must explicitly call the run API to process jobs, and a pushNotification can be used to notify the client of new jobs. pushNotification NotificationSetting !{enableAutoRun} Push Notification Push Notification Setting via GS2-Gateway when a new job is registered in the job queue. Only available when enableAutoRun is disabled. Used to prompt the client to call the run API to process the newly registered job. * Enabled only if enableAutoRun is “false” runNotification NotificationSetting  Run Notification Push Notification Setting via GS2-Gateway when a job in the job queue is executed. The notification includes the job result, allowing the client to display rewards or handle errors without additional API calls. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of job queue operations. Useful for tracking job registration, execution, retry, and failure for debugging and analytics. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data dump operation. The dump includes all job queue data and job execution results for the user. When complete, returns a URL to download the exported data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data cleaning operation. The cleaning removes all job queue data and job execution results for the user across all namespaces in this service. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Checks the progress of a previously initiated user data import operation. The import restores job queue data and job execution results from previously exported data. When complete, returns a URL to download the import log. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeJobsByUserId Get a list of jobs Retrieves a paginated list of jobs queued for the specified user. Jobs in the queue are waiting to be executed either manually via the Run API or automatically if enableAutoRun is enabled on the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Job nextPageToken string Page token to retrieve the rest of the listing Implementation Example getJobByUserId Get Job Retrieves the details of a specific job by its name, including the script ID, arguments, and retry configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Job Job Implementation Example pushByUserId Register jobs by specifying a user ID Registers one or more jobs to the user’s job queue (up to 10 at a time). Each job specifies a GS2-Script to execute, its arguments, and a maximum retry count. If enableAutoRun is enabled on the namespace, jobs are executed immediately and asynchronously after registration, and the autoRun flag in the response is set to true. If enableAutoRun is disabled, jobs are queued and must be executed manually via the Run API, with the autoRun flag set to false. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID jobs List 0 ~ 10 items List of jobs to add timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Jobs added autoRun bool? Implementation Example run Execute Job Executes the next job in the requesting user’s job queue. If enableAutoRun is enabled on the namespace, this API returns immediately with isLastJob=true since jobs are executed automatically. After successful execution, a run notification is sent if configured on the namespace. The response indicates whether this was the last job in the queue via the isLastJob flag. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Job Job result JobResultBody Job execution result body isLastJob bool? Implementation Example runByUserId Execute a job by specifying a user ID Executes the next job in the specified user’s job queue. If enableAutoRun is enabled on the namespace, this API returns immediately with isLastJob=true since jobs are executed automatically. After successful execution, a run notification is sent if configured on the namespace. The response indicates whether this was the last job in the queue via the isLastJob flag. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Job Job result JobResultBody Job execution result body isLastJob bool? Implementation Example deleteJob Delete job Deletes a specific job from the requesting user’s job queue. The job is removed regardless of its execution state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. Result Type Description item Job Job deleted Implementation Example deleteJobByUserId Delete a job by specifying a user ID Deletes a specific job from the specified user’s job queue. The job is removed regardless of its execution state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Job Job deleted Implementation Example getJobResult Get Job execution result Retrieves the execution result of a specific job for the requesting user. The result includes the HTTP status code and response body returned by the executed GS2-Script. You can optionally specify a try number to retrieve the result of a specific retry attempt. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. tryNumber int 0 ~ 10000 Number of attempts Result Type Description item JobResult Job execution result Implementation Example getJobResultByUserId Get job execution results by specifying a user ID Retrieves the execution result of a specific job for the specified user. The result includes the HTTP status code and response body returned by the executed GS2-Script. You can optionally specify a try number to retrieve the result of a specific retry attempt. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. tryNumber int 0 ~ 10000 Number of attempts timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item JobResult Job execution result Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-JobQueue SDK for various programming languages\n","title":"GS2-JobQueue SDK API Reference","url":"/api_reference/job_queue/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of encryption key operations. Useful for auditing key usage such as encryption and decryption requests. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Key Encryption Key The GRN of the Encryption Key to be created here must be specified when encryption processing is required by GS2. The contents of the specific Encryption Key will not be disclosed outside of GS2, and encryption and decryption can be performed securely. Details  keyId string * ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision GitHubApiKey GitHub API Key GS2 has several interfaces for uploading files such as master data and GS2-Deploy template files. For these interfaces, instead of uploading data, GS2 provides an interface to reflect settings from a specific branch or tag in a specific repository on GitHub. This interface stores the GitHub API Key needed to use this interface. Details  apiKeyId string * ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars GitHub API Key name GitHub API Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description encryptionKeyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace Creates a new key management namespace. The namespace serves as a container for encryption keys and GitHub API keys. Encryption keys within the namespace are used for data encryption/decryption across GS2 services, and GitHub API keys are used for master data operations from GitHub repositories. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of encryption key operations. Useful for auditing key usage such as encryption and decryption requests. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Updates the settings of the specified key management namespace. You can change the description and log settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of encryption key operations. Useful for auditing key usage such as encryption and decryption requests. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace updated Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example describeKeys Get a list of Encryption Keys Retrieves a paginated list of encryption keys in the specified namespace. Encryption keys are used for encrypting and decrypting data across GS2 services, such as securing transactions and protecting sensitive configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Encryption Key name prefix 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 List of Encryption Keys nextPageToken string Page token to retrieve the rest of the listing Implementation Example createKey Create a new Encryption Key Creates a new encryption key with an automatically generated random secret. The generated key can be used for encrypting and decrypting data via the Encrypt/Decrypt APIs. The secret itself is never exposed through the API; only the key metadata (name, description, GRN) is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description Result Type Description item Key Encryption Key created Implementation Example updateKey Update Encryption Key Updates the description of an existing encryption key. The encryption secret is not changed; only metadata can be updated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). keyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description Result Type Description item Key Encryption Key updated Implementation Example getKey Get Encryption Key Retrieves the metadata of a specific encryption key. The encryption secret is not included in the response for security reasons. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). keyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Key Encryption Key Implementation Example deleteKey Delete Encryption Key Deletes the specified encryption key and its secret permanently. Data previously encrypted with this key will no longer be decryptable after deletion. Ensure that no other services depend on this key before deleting it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). keyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Key Encryption Key deleted Implementation Example encrypt Encrypt data Encrypts the provided plaintext data using the specified encryption key. The encrypted result is returned as a Base64-encoded string. The maximum data size is 512KB. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). keyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). data string  ~ 524288 chars Result Type Description data string Encrypted Data Implementation Example decrypt Decrypt data Decrypts the provided Base64-encoded encrypted data using the specified encryption key. The data must have been encrypted with the same key; otherwise decryption will fail. Returns the original plaintext data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). keyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). data string  ~ 524288 chars Result Type Description data string decrypted data Implementation Example describeGitHubApiKeys Get a list of GitHub API Keys Retrieves a paginated list of GitHub API keys registered in the specified namespace. GitHub API keys are used for fetching master data from GitHub repositories via the UpdateFromGitHub APIs in other GS2 services. The API key values are stored encrypted and are not included in the listing response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of GitHub API Keys nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGitHubApiKey Create a new API key for GitHub Registers a new GitHub API key in the specified namespace. The API key value is encrypted using the specified encryption key (encryptionKeyName) before being stored, ensuring secure management. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars GitHub API Key name GitHub API Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description encryptionKeyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GitHubApiKey GitHub API Key created Implementation Example updateGitHubApiKey Update GitHub API Key Updates the settings of an existing GitHub API key. You can change the description, API key value, and the encryption key used for storage. The new API key value is re-encrypted with the specified encryption key. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). apiKeyName string  ~ 128 chars GitHub API Key name GitHub API Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description encryptionKeyName string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GitHubApiKey GitHub API Key updated Implementation Example getGitHubApiKey Get GitHub API Key Retrieves the metadata of a specific GitHub API key. The actual API key value is not included in the response for security reasons. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). apiKeyName string  ~ 128 chars GitHub API Key name GitHub API Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GitHubApiKey GitHub API Key Implementation Example deleteGitHubApiKey Delete GitHub API Key Deletes the specified GitHub API key and its encrypted value permanently. After deletion, services that reference this API key for GitHub master data updates will no longer be able to access GitHub repositories. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). apiKeyName string  ~ 128 chars GitHub API Key name GitHub API Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GitHubApiKey GitHub API Key deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Key SDK for various programming languages\n","title":"GS2-Key SDK API Reference","url":"/api_reference/key/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing limit operations such as counting up and resetting counters. countUpScript ScriptSetting Script to execute when counting up Script Trigger Reference - countUp logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of limit operations. Useful for tracking counter increments, resets, and limit checks for debugging and analytics. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Counter Current Counter Value Tracks the current usage count for a specific counter under a limit model for each user. Multiple counters can exist under a single limit model (e.g., one counter per quest for one-time rewards). The count is compared against a maximum value specified at the time of the count-up operation, and is automatically reset to zero based on the limit model’s reset schedule. Details  counterId string * ~ 1024 chars Counter A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. name string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. userId string  ~ 128 chars User ID count int 0 0 ~ 2147483646 Count Value The current usage count for this counter. Incremented by the countUp operation and compared against the maximum value specified at that time. Automatically reset to zero when the limit model’s reset timing is reached. nextResetAt long Next Reset Timing The timestamp at which this counter will next be reset to zero, calculated from the limit model’s reset schedule. For “notReset” type, this value is not set. Automatically recalculated after each reset occurs. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LimitModel Usage Limit Model Usage Limit Model allows you to set the timing for resetting the usage count. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. Additionally, the maximum value for usage Limits is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha: Items purchasable when the purchase counter is under 3 When the above items are unavailable, another item purchasable if the purchase counter is under 5 The design assumes the ability to switch the “maximum count” based on the situation. Details  limitModelId string * ~ 1024 chars Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Usage Limit Model name Usage Limit 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days” CurrentLimitMaster Currently active Usage Limit Model master data This master data defines the Usage Limit Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Limit Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data LimitModelMaster Usage Limit Model Master Usage Limit Model Master is data used to edit and manage Usage Limit Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Usage Limit Model actually referenced by the game. You can configure when the usage count is reset for a limit. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. All times must be specified in Coordinated Universal Time (UTC). In addition, the maximum allowed value for a limit is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha system: A product that can be purchased if the purchase count counter is less than 3 Another product that becomes available if the above product cannot be purchased but the purchase count counter is less than 5 In this way, the system is designed so that the maximum allowed count can change dynamically based on the situation. Furthermore, multiple counters can be created under a single Usage Limit Model. For example, if there are several quest rewards that can each be claimed only once, you do not need to create a separate Usage Limit Model for each quest. Instead, you can create one Usage Limit Model and assign separate counters per quest, preventing an unnecessary increase in the number of configuration patterns. Details  limitModelId string * ~ 1024 chars Usage Limit Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing limit operations such as counting up and resetting counters. countUpScript ScriptSetting Script to execute when counting up Script Trigger Reference - countUp logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of limit operations. Useful for tracking counter increments, resets, and limit checks for debugging and analytics. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing limit operations such as counting up and resetting counters. countUpScript ScriptSetting Script to execute when counting up Script Trigger Reference - countUp logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of limit operations. Useful for tracking counter increments, resets, and limit checks for debugging and analytics. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeCounters Get a list of Counters Retrieves a paginated list of the requesting user’s counters. Can optionally filter by limit model name to get counters only for a specific model. Each counter tracks the number of times a specific action has been performed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token limitName string ~ 128 chars Usage Limit Model name Usage Limit 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 List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeCountersByUserId Get a list of Counters by specifying a user ID Retrieves a paginated list of counters for the specified user. Can optionally filter by limit model name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID limitName string ~ 128 chars Usage Limit Model name Usage Limit 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example getCounter Get a Counter Retrieves the requesting user’s counter for the specified limit model and counter name. Returns the current count value. If the counter does not exist, no data will be returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. accessToken string  ~ 128 chars Access token counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. Result Type Description item Counter Counter Implementation Example getCounterByUserId Get a Counter by specifying a user ID Retrieves the specified user’s counter for the given limit model and counter name. Returns the current count value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. userId string  ~ 128 chars User ID counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter Implementation Example countUp Count-up Increments the requesting user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created with a count of 0 before incrementing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. accessToken string  ~ 128 chars Access token countUpValue int 1 1 ~ 2147483646 Amount to count up maxValue int 1 ~ 2147483646 Maximum value allowed to count up Result Type Description item Counter Counter with increased count Implementation Example countUpByUserId Count-up by specifying a user ID Increments the specified user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. userId string  ~ 128 chars User ID countUpValue int 1 1 ~ 2147483646 Amount to count up maxValue int 1 ~ 2147483646 Maximum value allowed to count up timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter with increased count Implementation Example countDownByUserId Count-down by specifying a user ID Decrements the specified user’s counter by the specified count-down value. The counter value will not go below 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. userId string  ~ 128 chars User ID countDownValue int 1 1 ~ 2147483646 Amount to count down timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter with increased count Implementation Example deleteCounterByUserId Delete Counter by specifying a user ID Deletes the specified user’s counter, resetting the usage count. This effectively removes the limit restriction for this counter, allowing the user to start counting from 0 again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. userId string  ~ 128 chars User ID counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter deleted Implementation Example verifyCounter Verify Counter value Verifies that the requesting user’s counter value satisfies the specified condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. If the condition is not met, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count int 0 0 ~ 2147483646 Count Value The current usage count for this counter. Incremented by the countUp operation and compared against the maximum value specified at that time. Automatically reset to zero when the limit model’s reset timing is reached. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Counter Counter deleted Implementation Example verifyCounterByUserId Verify Counter value by specifying a user ID Verifies that the specified user’s counter value satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count int 0 0 ~ 2147483646 Count Value The current usage count for this counter. Incremented by the countUp operation and compared against the maximum value specified at that time. Automatically reset to zero when the limit model’s reset timing is reached. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter deleted Implementation Example describeLimitModels Get a list of Usage Limit Models Retrieves the list of currently active usage limit models. The models define the counter reset timing (e.g., not reset, daily, weekly, monthly) and related settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Usage Limit Models Implementation Example getLimitModel Get Usage Limit Model Retrieves the specified usage limit model. The model defines the reset type and timing for counters associated with this limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item LimitModel Usage Limit Model Implementation Example exportMaster Export Usage Limit Model Master in a master data format that can be activated Exports the currently active usage limit model masters in a format suitable for activation. The exported data can be used to update master data in another namespace or stored as a backup. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentLimitMaster Usage Usage Limit Model Master that can be activated Implementation Example getCurrentLimitMaster Get currently active Usage Limit Model master data Retrieves the currently active usage limit model master data for the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentLimitMaster Currently active Usage Limit Model master data Implementation Example preUpdateCurrentLimitMaster Update currently active Usage Limit Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentLimitMaster Update currently active Usage Limit Model master data Updates the currently active usage limit model master data. Supports two modes: ‘direct’ for inline settings, and ‘preUpload’ for applying settings previously uploaded via the 3-phase update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentLimitMaster Updated master data of the currently active Usage Limit Models Implementation Example updateCurrentLimitMasterFromGitHub Update currently active Usage Limit Model master data from GitHub Updates the currently active usage limit model master data by fetching it from a specified GitHub repository. The API key stored in GS2-Key is used for authentication, and you can specify the branch, tag, or commit hash to checkout. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentLimitMaster Updated master data of the currently active Usage Limit Models Implementation Example describeLimitModelMasters Get a list of Usage Limit Model Masters Retrieves a paginated list of usage limit model masters. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Usage Limit Model name prefix 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 List of Usage Limit Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createLimitModelMaster Create a new Usage Limit Model Master Creates a new usage limit model master with the specified reset timing configuration. The reset type can be notReset, daily, weekly, monthly, or days, with configurable reset hour and day of week/month for periodic resets. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days” Result Type Description item LimitModelMaster Usage Limit Model Master created Implementation Example getLimitModelMaster Get a Usage Limit Model Master Retrieves the specified usage limit model master, including its reset type and timing configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item LimitModelMaster Usage Limit Model Master Implementation Example updateLimitModelMaster Update Usage Limit Model Master Updates the specified usage limit model master. You can modify the description, metadata, and reset timing settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days” Result Type Description item LimitModelMaster Usage Limit Model Master updated Implementation Example deleteLimitModelMaster Delete Usage Limit Model Master Deletes the specified usage limit model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model name Usage Limit Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item LimitModelMaster Usage Limit Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Limit SDK for various programming languages\n","title":"GS2-Limit SDK API Reference","url":"/api_reference/limit/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Mutex Mutex The mutex provided by GS2 is a type of re-entrant lock. When acquiring a lock, a transaction ID is specified, and the lock can be acquired again only if the same transaction ID is specified. Since it has a reference counter, the same number of unlock operations are required when releasing it. Details  mutexId string * ~ 1024 chars Mutex A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server ttlAt long The absolute time 1 hour after the current time Expiration datetime Unix time, milliseconds revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example lock Get Mutex Acquires a mutex lock on the specified property for the requesting user. The lock is held for the specified TTL (time-to-live) duration in seconds. If the same transactionId acquires the lock again, the reference count is incremented (reentrant lock). If a different transactionId attempts to lock an already locked mutex, the operation will fail. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. accessToken string  ~ 128 chars Access token transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. ttl long  0 ~ 9223372036854775805 Duration of lock acquisition (seconds) Result Type Description item Mutex Mutex Implementation Example lockByUserId Get Mutex by specifying a user ID Acquires a mutex lock on the specified property for the specified user. The lock is held for the specified TTL duration in seconds. If the same transactionId acquires the lock again, the reference count is incremented (reentrant lock). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. userId string  ~ 128 chars User ID transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. ttl long  0 ~ 9223372036854775805 Duration of lock acquisition (seconds) timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mutex Mutex Implementation Example unlock Release Mutex Releases a mutex lock on the specified property for the requesting user. The transactionId must match the one used to acquire the lock. The reference count is decremented, and the lock is fully released when it reaches 0. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. accessToken string  ~ 128 chars Access token transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. Result Type Description item Mutex Mutex Implementation Example unlockByUserId Release Mutex by specifying a user ID Releases a mutex lock on the specified property for the specified user. The transactionId must match the one used to acquire the lock. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. userId string  ~ 128 chars User ID transactionId string  ~ 256 chars Transaction ID An identifier for the transaction acquiring the lock. This ID is used to implement re-entrant locking behavior: if a lock request specifies the same transaction ID as the current lock holder, the lock is successfully acquired again and the reference count is incremented. A lock request with a different transaction ID will be rejected while the lock is held. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mutex Mutex Implementation Example getMutex Get Mutex status Retrieves the current mutex status for the requesting user’s specified property. Returns the mutex information including the transaction ID, reference count, and TTL expiration time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. Result Type Description item Mutex Mutex Implementation Example getMutexByUserId Get Mutex status by specifying a user ID Retrieves the current mutex status for the specified user’s property. Returns the mutex information including the transaction ID, reference count, and TTL expiration time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mutex Mutex Implementation Example deleteMutexByUserId Delete Mutex Forcibly deletes the mutex on the specified property, regardless of the transaction ID or reference count. This is an administrative operation that immediately releases the lock. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier for the resource to be locked, determining which resource the lock is protecting. When multiple processes need exclusive access to the same resource, they should specify the same property ID. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Mutex Mutex deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Lock SDK for various programming languages\n","title":"GS2-Lock SDK API Reference","url":"/api_reference/lock/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description type string (enum) enum {   “gs2”,   “bigquery”,   “firehose” } “gs2” Log Export Method Determines the destination for exported log data. “gs2” stores logs within GS2’s managed storage with built-in search and analysis capabilities. “bigquery” exports logs to Google BigQuery for advanced analytics. “firehose” streams logs to Amazon Kinesis Data Firehose for delivery to S3, Redshift, or other AWS destinations. Definition Description “gs2” Management by GS2 “bigquery” Export to BigQuery “firehose” Export to Kinesis Firehose gcpCredentialJson string {type} == “bigquery”  ~ 5120 chars GCP Credentials GCP credential JSON for authenticating when exporting logs to BigQuery. The service account must have BigQuery Data Editor permissions on the target dataset. * Required if type is “bigquery” bigQueryDatasetName string {type} == “bigquery”  ~ 1024 chars BigQuery Dataset Name The name of the BigQuery dataset where log data will be exported. The dataset must already exist in the GCP project associated with the provided credentials. * Required if type is “bigquery” logExpireDays int {type} in [“gs2”, “bigquery”]  0 ~ 3650 Log Retention Period (days) The number of days to retain log data. Logs older than this period are automatically deleted. Applicable when the export method is “gs2” or “bigquery”. Maximum 3650 days (approximately 10 years). * Required if type is “gs2”,“bigquery” awsRegion string {type} == “firehose”  ~ 256 chars AWS Region The AWS region where the Kinesis Data Firehose delivery stream is located (e.g., us-east-1, ap-northeast-1). * Required if type is “firehose” awsAccessKeyId string {type} == “firehose”  ~ 256 chars AWS Access Key ID The AWS access key ID for authenticating with Kinesis Data Firehose. The IAM user must have permissions to put records to the specified Firehose delivery stream. * Required if type is “firehose” awsSecretAccessKey string {type} == “firehose”  ~ 256 chars AWS Secret Access Key The AWS secret access key paired with the access key ID for Kinesis Data Firehose authentication. * Required if type is “firehose” firehoseStreamName string {type} == “firehose”  ~ 256 chars Kinesis Firehose Stream Name The name of the Kinesis Data Firehose delivery stream to which log data is sent. * Required if type is “firehose” firehoseCompressData string (enum) enum {   “none”,   “gzip” } {type} == “firehose” “none” Compress Data for Kinesis Firehose Whether to compress log data before sending to Kinesis Data Firehose. Gzip compression reduces data transfer volume and storage costs. Definition Description “none” Do not compress “gzip” Gzip * Enabled only if type is “firehose” status string “ACTIVE” ~ 128 chars Status The current operational status of this namespace. Indicates whether the namespace is active and accepting log data. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision AccessLog Access log This log records requests to microservices and their responses. Details  timestamp long  Timestamp The date and time when the API request was processed. requestId string  ~ 1024 chars Request ID A unique identifier assigned to each API request. Used for tracking and debugging specific API calls. service string  ~ 1024 chars Microservice Type The name of the GS2 microservice that handled the request (e.g., account, inventory, limit). method string  ~ 1024 chars Microservice Method The specific API method that was called on the microservice (e.g., createNamespace, getItem). userId string ~ 128 chars User ID request string  ~ 10485760 chars Request Content The full request parameters sent to the API in JSON format. result string  ~ 10485760 chars Response Content The full response returned by the API in JSON format, including both successful results and error details. AccessLogCount Access Log Aggregation An aggregated count of access log entries, grouped by microservice type, method, and user. Used for analyzing API usage patterns and identifying frequently called endpoints. Details  service string ~ 1024 chars Microservice Type The name of the GS2 microservice. Used as a grouping key for aggregation. method string ~ 1024 chars Microservice Method The specific API method. Used as a grouping key for aggregation. userId string ~ 128 chars User ID count long  0 ~ 9223372036854775805 Count The total number of access log entries matching the grouping criteria. IssueStampSheetLog Issued Transaction Log Records the issuance of distributed transactions. Each entry captures the acquire action and associated consume actions (tasks) that were packaged together as a single transaction at the time of issuance. Details  timestamp long  Timestamp The date and time when the transaction was issued. transactionId string  ~ 1024 chars Transaction ID The unique identifier of the issued distributed transaction. service string  ~ 1024 chars Microservice Type The name of the GS2 microservice that issued the transaction. method string  ~ 1024 chars Microservice Method The specific API method that triggered the transaction issuance. userId string  ~ 128 chars User ID action string  ~ 1024 chars Acquire Action The acquire action included in the transaction, specifying what the user will receive upon execution. args string  ~ 5242880 chars Arguments The parameters for the acquire action in JSON format. tasks List 0 ~ 10 items List of Consume Actions The consume actions that are bundled with this transaction. These are executed before the acquire action to consume resources as preconditions. IssueStampSheetLogCount Issued Transaction Log Aggregation An aggregated count of transaction issuance log entries, grouped by microservice type, method, user, and action. Used for analyzing the volume and distribution of distributed transactions issued across services. Details  service string ~ 1024 chars Microservice Type The name of the GS2 microservice that issued the transaction. method string ~ 1024 chars Microservice Method The specific API method that triggered the transaction issuance. userId string ~ 128 chars User ID action string ~ 1024 chars Acquire Action The type of acquire action included in the issued transaction. count long  0 ~ 9223372036854775805 Count The total number of transaction issuance log entries matching the grouping criteria. ExecuteStampSheetLog Transaction Execution Log This is a log of the execution details of the transaction for each microservice. Details  timestamp long  Timestamp The date and time when the acquire action was executed. transactionId string  ~ 1024 chars Transaction ID The unique identifier of the distributed transaction that this acquire action belongs to. service string  ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the acquire action (e.g., inventory, experience). method string  ~ 1024 chars Microservice Method The specific method invoked on the microservice to execute the acquire action. userId string  ~ 128 chars User ID action string  ~ 1024 chars Acquire Action The type of acquire action that was executed (e.g., Gs2Inventory:AcquireItemSetByUserId, Gs2Experience:AddExperienceByUserId). args string  ~ 5242880 chars Arguments The parameters passed to the acquire action in JSON format. ExecuteStampSheetLogCount Acquire Action Execution Log Aggregation An aggregated count of acquire action execution log entries, grouped by microservice type, method, user, and action. Used for analyzing how frequently each type of acquire action is being executed. Details  service string ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the acquire action. method string ~ 1024 chars Microservice Method The specific method invoked to execute the acquire action. userId string ~ 128 chars User ID action string ~ 1024 chars Acquire Action The type of acquire action that was executed. count long  0 ~ 9223372036854775805 Count The total number of acquire action execution log entries matching the grouping criteria. ExecuteStampTaskLog Consume Action Execution Log This is a log of the execution details of the consume action for each microservice. Details  timestamp long  Timestamp The date and time when the consume action was executed. taskId string  ~ 1024 chars Task ID The unique identifier of the transaction that was executed. service string  ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the consume action (e.g., inventory, money). method string  ~ 1024 chars Microservice Method The specific method invoked on the microservice to execute the consume action. userId string  ~ 128 chars User ID action string  ~ 1024 chars Consume Action The type of consume action that was executed (e.g., Gs2Inventory:ConsumeItemSetByUserId, Gs2Money:WithdrawByUserId). args string  ~ 5242880 chars Arguments The parameters passed to the consume action in JSON format. ExecuteStampTaskLogCount Consume Action Execution Log Aggregation An aggregated count of consume action execution log entries, grouped by microservice type, method, user, and action. Used for analyzing how frequently each type of consume action is being executed. Details  service string ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the consume action. method string ~ 1024 chars Microservice Method The specific method invoked to execute the consume action. userId string ~ 128 chars User ID action string ~ 1024 chars Consume Action The type of consume action that was executed. count long  0 ~ 9223372036854775805 Count The total number of consume action execution log entries matching the grouping criteria. InGameLog In-game Log A custom log entry sent from the game client or server-side scripts. Unlike access logs which are automatically generated by GS2 API calls, in-game logs are explicitly sent by game developers to record game-specific events such as player actions, game state changes, or business metrics. Details  timestamp long  Timestamp The date and time when the in-game log was sent. requestId string  ~ 1024 chars Request ID A unique identifier assigned to this log entry for deduplication and tracking. userId string ~ 128 chars User ID tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). payload string  ~ 10485760 chars Payload The custom log data in JSON format. Can contain any game-specific information such as player actions, game state, or business metrics. Maximum 10MB. AccessLogWithTelemetry Access log with telemetry information This log records requests to microservices and their responses. The log includes response time and context information of the caller. Details  timestamp long  Timestamp The date and time when the API request was processed. sourceRequestId string  ~ 1024 chars Source Request ID The request ID of the original caller that triggered this request. Used to trace related API calls back to the originating request. requestId string  ~ 1024 chars Request ID A unique identifier assigned to this specific API request. duration long  0 ~ 9223372036854775805 Duration (ms) The time in milliseconds taken to process this API request from receipt to response. service string  ~ 1024 chars Microservice Type The name of the GS2 microservice that handled the request (e.g., account, inventory, limit). method string  ~ 1024 chars Microservice Method The specific API method that was called on the microservice (e.g., createNamespace, getItem). userId string ~ 128 chars User ID request string  ~ 10485760 chars Request Content The full request parameters sent to the API in JSON format. result string  ~ 10485760 chars Response Content The full response returned by the API in JSON format. status string (enum) enum {   “ok”,   “error” }  Status The result status of the API request. “ok” indicates successful processing, “error” indicates a failure occurred. Definition Description “ok” OK “error” Error Insight GS2-Insight is a tool for visualizing and analyzing access logs stored in GS2-Log. GS2-Insight itself is open source and available on github. https://github.com/gs2io/gs2-insight Here, you can launch and use the publicly available open source code on-demand without hosting it yourself. GS2-Insight activated on demand can be used for up to 2 hours. If you wish to use it for more than 2 hours, please host it yourself. Details  insightId string * ~ 1024 chars GS2-Insight A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Name taskId string ~ 128 chars Task ID host string ~ 256 chars Host Name password string  ~ 32 chars Password status string (enum) enum {   “ALLOCATING”,   “LAUNCHING”,   “ACTIVE”,   “DELETED” } “ALLOCATING” Status Definition Description “ALLOCATING” Server assignment in progress “LAUNCHING” during startup “ACTIVE” Active “DELETED” Deleted createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Dashboard Dashboard A customizable dashboard for visualizing log data and metrics. Each dashboard stores its layout and widget configuration as a JSON payload, allowing users to create tailored views of their log analytics. Details  dashboardId string * ~ 1024 chars Dashboard A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Dashboard Name displayName string  ~ 256 chars Display Name A human-readable name for this dashboard, shown in the dashboard list and header. description string ~ 1024 chars Description payload string  ~ 1048576 chars Payload The dashboard configuration in JSON format, containing widget definitions, layout information, query settings, and visualization options. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server FacetModel Facet Model Defines a facet field available for filtering and aggregating log data. Facets allow users to narrow down log search results by specific dimensions such as service name, method, status, or custom fields. Details  facetModelId string * ~ 1024 chars Facet Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). type string (enum) enum {   “string”,   “double”,   “measure” }  Facet Data Type The data type of the facet field. “string” for categorical values with value counts, “double” for numeric values with range filtering, “measure” for measurement values with statistical analysis. Definition Description “string” String “double” Double “measure” Measure displayName string  ~ 128 chars Display Name A human-readable name for this facet, shown in the log search UI. order int 0 0 ~ 100000 Display Order The sort order for displaying this facet in the UI. Lower values appear first. MetricModel Metric Model Defines a metric that can be monitored and visualized. Predefined metrics include request count, request duration, and error rates (4xx/5xx) for each GS2 microservice. Each metric has associated labels for grouping and filtering. Details  name string  ~ 128 chars Metric Name The unique identifier for this metric (e.g., “RequestCount”, “RequestDuration”, “Error4xxCount”, “Error5xxCount”). Service-specific metrics are prefixed with the service name. type string (enum) enum {   “string”,   “double”,   “measure” }  Metric Data Type The data type of the metric values. “double” is used for numeric counts, “measure” is used for duration/latency measurements. Definition Description “string” String “double” Double “measure” Measure labels List [] 0 ~ 10 items Labels The label names associated with this metric, used for grouping and filtering metric data (e.g., “service”, “method”, “namespaceName”). Labels define the dimensions along which the metric can be broken down. AggregationConfig Aggregation Config Configuration for how log data or metrics should be aggregated when querying timeseries data. Specifies the aggregation function (count, average, percentile, etc.) and the target field to aggregate. Details  type string (enum) enum {   “count”,   “unique”,   “sum”,   “avg”,   “max”,   “min”,   “p90”,   “p95”,   “p99” } “count” Aggregation type: - unique : Unique value count - avg : Average - max : Maximum - min : Minimum - p90 : 90th percentile - p99 : 99th percentile Definition Description “count” Record count “unique” Unique value count “sum” Sum “avg” Average “max” Maximum “min” Minimum “p90” 90th percentile “p95” 95th percentile “p99” 99th percentile field string ~ 128 chars Target field for aggregation (required except for count) Facet Facet The result of a facet query on log data, containing the distribution of values for a specific field. For string fields, provides value counts; for numeric fields, provides the value range under current filters and the global range for UI slider display. Details  field string  ~ 128 chars Facet Field Name values List [] 0 ~ 100 items Array of values and counts for string facets range NumericRange Numeric range under current filter conditions globalRange NumericRange Full data range before filters (for UI slider range) FacetValueCount Facet Value Count A single value and its occurrence count within a string facet result. Represents how many log entries have a specific value for a given facet field. Details  value string  ~ 256 chars Facet Value count long  0 ~ 9223372036854775805 Count of logs with this value Label Label A key-value pair used to annotate log entries and metrics for categorization, filtering, and grouping. Details  key string  ~ 128 chars Label Key The key name for this label (e.g., “service”, “method”, “namespaceName”). value string  ~ 256 chars Label Value The value for this label corresponding to the key. LogEntry Log Entry A single log record within a trace, representing one processing step or API call. Contains the raw log data, processing duration, severity status, and associated labels for categorization. Details  timestamp long  Timestamp The date and time when this log entry was recorded. status string (enum) enum {   “ok”,   “info”,   “notice”,   “error”,   “warn”,   “emag” }  Status The severity level of this log entry, ranging from informational to emergency. Definition Description “ok” OK “info” Information “notice” Notice “error” Error “warn” Warning “emag” Emergency duration long 0 0 ~ 9223372036854775805 Duration (nanoseconds) The processing time for this log entry in nanoseconds. line string  ~ 10485760 chars Raw Log Line Data The raw log data in JSON format, containing the full details of the processing step including request/response information. labels List [] 0 ~ 128 items Labels Key-value pairs attached to this log entry for categorization and filtering (e.g., service name, method, request ID). NumericRange Numeric range. range : Range under current filter conditions (other filters applied, self excluded) globalRange : Full data range before filters (used for UI slider range) Details  min double  0 ~ 281474976710654 Minimum Value max double  0 ~ 281474976710654 Maximum Value TimeseriesMetadata Timeseries Metadata Metadata about a timeseries query result, describing the series keys present in the data and the fields used for grouping. Used by the client to properly interpret and display the timeseries data. Details  keys List [] 0 ~ 10 items List of series keys in the data groupBy List [] 0 ~ 10 items Field(s) used for grouping TimeseriesPoint Timeseries Point A single data point in a timeseries, representing aggregated values at a specific timestamp. Contains one or more values, each corresponding to a different group when grouping is applied. Details  timestamp long  Timestamp values List [] 0 ~ 10000 items Values for each group at this timestamp TimeseriesValue Timeseries Value A single aggregated value within a timeseries data point, keyed by group. When data is grouped (e.g., by service or method), each group has its own value; when ungrouped, the key is “count”. Details  key string  ~ 256 chars Group key (\"count\" if no grouping) value double  0 ~ 281474976710654 Aggregated value Trace Trace A distributed trace that groups related log entries (spans) across microservice calls into a single request flow. Enables end-to-end visibility of how a user’s API request propagates through multiple GS2 microservices. Details  traceId string  UUID ~ 36 chars Trace ID A unique identifier for this trace, shared across all related log entries (spans) in the request flow. spans List [] 0 ~ 100 items Spans The list of log entries (spans) that make up this trace, representing each processing step in the request flow across microservices. truncated bool false Truncated Indicates whether the spans list was truncated due to exceeding the maximum number of entries. When true, some spans in the trace are not included in the response. InGameLogTag In-game Log Tag A key-value pair used to annotate in-game log entries for filtering and categorization. Each tag key must be unique within a single log entry. Details  key string  ~ 64 chars Tag Key The key name for this tag. Used as the filter criterion when searching in-game logs. value string  ~ 128 chars Tag Value The value for this tag. Combined with the key, enables filtering logs by specific criteria (e.g., key=“stageId”, value=“stage-001”). Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description type string (enum) enum {   “gs2”,   “bigquery”,   “firehose” } “gs2” Log Export Method Determines the destination for exported log data. “gs2” stores logs within GS2’s managed storage with built-in search and analysis capabilities. “bigquery” exports logs to Google BigQuery for advanced analytics. “firehose” streams logs to Amazon Kinesis Data Firehose for delivery to S3, Redshift, or other AWS destinations. Definition Description “gs2” Management by GS2 “bigquery” Export to BigQuery “firehose” Export to Kinesis Firehose gcpCredentialJson string {type} == “bigquery”  ~ 5120 chars GCP Credentials GCP credential JSON for authenticating when exporting logs to BigQuery. The service account must have BigQuery Data Editor permissions on the target dataset. * Required if type is “bigquery” bigQueryDatasetName string {type} == “bigquery”  ~ 1024 chars BigQuery Dataset Name The name of the BigQuery dataset where log data will be exported. The dataset must already exist in the GCP project associated with the provided credentials. * Required if type is “bigquery” logExpireDays int {type} in [“gs2”, “bigquery”]  0 ~ 3650 Log Retention Period (days) The number of days to retain log data. Logs older than this period are automatically deleted. Applicable when the export method is “gs2” or “bigquery”. Maximum 3650 days (approximately 10 years). * Required if type is “gs2”,“bigquery” awsRegion string {type} == “firehose”  ~ 256 chars AWS Region The AWS region where the Kinesis Data Firehose delivery stream is located (e.g., us-east-1, ap-northeast-1). * Required if type is “firehose” awsAccessKeyId string {type} == “firehose”  ~ 256 chars AWS Access Key ID The AWS access key ID for authenticating with Kinesis Data Firehose. The IAM user must have permissions to put records to the specified Firehose delivery stream. * Required if type is “firehose” awsSecretAccessKey string {type} == “firehose”  ~ 256 chars AWS Secret Access Key The AWS secret access key paired with the access key ID for Kinesis Data Firehose authentication. * Required if type is “firehose” firehoseStreamName string {type} == “firehose”  ~ 256 chars Kinesis Firehose Stream Name The name of the Kinesis Data Firehose delivery stream to which log data is sent. * Required if type is “firehose” firehoseCompressData string (enum) enum {   “none”,   “gzip” } {type} == “firehose” “none” Compress Data for Kinesis Firehose Whether to compress log data before sending to Kinesis Data Firehose. Gzip compression reduces data transfer volume and storage costs. Definition Description “none” Do not compress “gzip” Gzip * Required if type is “firehose” Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description type string (enum) enum {   “gs2”,   “bigquery”,   “firehose” } “gs2” Log Export Method Determines the destination for exported log data. “gs2” stores logs within GS2’s managed storage with built-in search and analysis capabilities. “bigquery” exports logs to Google BigQuery for advanced analytics. “firehose” streams logs to Amazon Kinesis Data Firehose for delivery to S3, Redshift, or other AWS destinations. Definition Description “gs2” Management by GS2 “bigquery” Export to BigQuery “firehose” Export to Kinesis Firehose gcpCredentialJson string {type} == “bigquery”  ~ 5120 chars GCP Credentials GCP credential JSON for authenticating when exporting logs to BigQuery. The service account must have BigQuery Data Editor permissions on the target dataset. * Required if type is “bigquery” bigQueryDatasetName string {type} == “bigquery”  ~ 1024 chars BigQuery Dataset Name The name of the BigQuery dataset where log data will be exported. The dataset must already exist in the GCP project associated with the provided credentials. * Required if type is “bigquery” logExpireDays int {type} in [“gs2”, “bigquery”]  0 ~ 3650 Log Retention Period (days) The number of days to retain log data. Logs older than this period are automatically deleted. Applicable when the export method is “gs2” or “bigquery”. Maximum 3650 days (approximately 10 years). * Required if type is “gs2”,“bigquery” awsRegion string {type} == “firehose”  ~ 256 chars AWS Region The AWS region where the Kinesis Data Firehose delivery stream is located (e.g., us-east-1, ap-northeast-1). * Required if type is “firehose” awsAccessKeyId string {type} == “firehose”  ~ 256 chars AWS Access Key ID The AWS access key ID for authenticating with Kinesis Data Firehose. The IAM user must have permissions to put records to the specified Firehose delivery stream. * Required if type is “firehose” awsSecretAccessKey string {type} == “firehose”  ~ 256 chars AWS Secret Access Key The AWS secret access key paired with the access key ID for Kinesis Data Firehose authentication. * Required if type is “firehose” firehoseStreamName string {type} == “firehose”  ~ 256 chars Kinesis Firehose Stream Name The name of the Kinesis Data Firehose delivery stream to which log data is sent. * Required if type is “firehose” firehoseCompressData string (enum) enum {   “none”,   “gzip” } {type} == “firehose” “none” Compress Data for Kinesis Firehose Whether to compress log data before sending to Kinesis Data Firehose. Gzip compression reduces data transfer volume and storage costs. Definition Description “none” Do not compress “gzip” Gzip * Required if type is “firehose” Result Type Description item Namespace Updated namespace Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Deleted namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example queryAccessLog Get a list of access logs Queries access logs within the specified time range with optional filtering by service, method, and user ID. Results include the total count and scan size in bytes. When searching periods longer than 7 days, the longTerm flag must be enabled, which may increase API execution fees due to larger scan volumes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service string ~ 1024 chars Microservice Type The name of the GS2 microservice that handled the request (e.g., account, inventory, limit). method string ~ 1024 chars Microservice Method The specific API method that was called on the microservice (e.g., createNamespace, getItem). userId string ~ 128 chars User ID begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 100 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Access Logs nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example countAccessLog Get aggregate results of access logs Aggregates access log counts within the specified time range, with optional classification by service, method, and/or user ID. Each classification flag controls whether results are grouped by that dimension. When the longTerm flag is enabled, periods longer than 7 days can be searched. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service bool false Classify by microservice type method bool false Classify by microservice method userId bool false Classify by user ID begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Aggregated access log nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example queryIssueStampSheetLog Get a list of transaction issue logs Queries transaction (transaction) issuance logs within the specified time range. Results can be filtered by service, method, user ID, and action type. Includes total count and scan size in the response. Enable the longTerm flag for searches exceeding 7 days. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service string ~ 1024 chars Microservice Type The name of the GS2 microservice that issued the transaction. method string ~ 1024 chars Microservice Method The specific API method that triggered the transaction issuance. userId string ~ 128 chars User ID action string ~ 1024 chars Acquire Action The acquire action included in the transaction, specifying what the user will receive upon execution. begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 100 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Transaction issue log nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example countIssueStampSheetLog Get aggregate results of transaction issue logs Aggregates transaction (transaction) issuance log counts within the specified time range, with optional classification by service, method, user ID, and/or action type. Each classification flag controls whether results are grouped by that dimension. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service bool false Classify by microservice type method bool false Classify by microservice method userId bool false Classify by user ID action bool false Classify by acquire actions begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Aggregated transaction issuance log nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example queryExecuteStampSheetLog Get a list of transaction execution logs Queries acquire action execution logs within the specified time range. Results can be filtered by service, method, user ID, and action type. Includes total count and scan size in the response. Enable the longTerm flag for searches exceeding 7 days. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service string ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the acquire action (e.g., inventory, experience). method string ~ 1024 chars Microservice Method The specific method invoked on the microservice to execute the acquire action. userId string ~ 128 chars User ID action string ~ 1024 chars Acquire Action The type of acquire action that was executed (e.g., Gs2Inventory:AcquireItemSetByUserId, Gs2Experience:AddExperienceByUserId). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 100 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Acquire Actions execution logs nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example countExecuteStampSheetLog Get aggregate results of acquire action execution logs Aggregates acquire action execution log counts within the specified time range, with optional classification by service, method, user ID, and/or action type. Each classification flag controls whether results are grouped by that dimension. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service bool false Classify by microservice type method bool false Classify by microservice method userId bool false Classify by user ID action bool false Classify by acquire actions begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Aggregated acquire actions execution nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example queryExecuteStampTaskLog Get a list of consume action execution logs Queries consume action execution logs within the specified time range. Results can be filtered by service, method, user ID, and action type. Includes total count and scan size in the response. Enable the longTerm flag for searches exceeding 7 days. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service string ~ 1024 chars Microservice Type The name of the GS2 microservice that executed the consume action (e.g., inventory, money). method string ~ 1024 chars Microservice Method The specific method invoked on the microservice to execute the consume action. userId string ~ 128 chars User ID action string ~ 1024 chars Consume Action The type of consume action that was executed (e.g., Gs2Inventory:ConsumeItemSetByUserId, Gs2Money:WithdrawByUserId). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 100 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of consume action execution log nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example countExecuteStampTaskLog Get aggregate results of consume action execution logs Aggregates consume action execution log counts within the specified time range, with optional classification by service, method, user ID, and/or action type. Each classification flag controls whether results are grouped by that dimension. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). service bool false Classify by microservice type method bool false Classify by microservice method userId bool false Classify by user ID action bool false Classify by acquire actions begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Aggregated consume action execution log nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example queryInGameLog Get a list of in-game logs Queries custom in-game logs within the specified time range with optional filtering by user ID and tags. In-game logs are developer-defined log entries that can contain arbitrary payload data and tags for classification. Enable the longTerm flag for searches exceeding 7 days. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). begin long The absolute time 1 hour prior to the current time Search range start date and time end long The absolute time 1 hour after the current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 100 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of in-game logs nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example sendInGameLog Send in-game log Sends a custom in-game log entry for the requesting user with the specified tags and payload. Tags are used for classification and filtering when querying logs. The payload can contain arbitrary data defined by the developer. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). payload string  ~ 10485760 chars Payload The custom log data in JSON format. Can contain any game-specific information such as player actions, game state, or business metrics. Maximum 10MB. Result Type Description item InGameLog In-game log Implementation Example sendInGameLogByUserId Send in-game log by specifying a user ID Sends a custom in-game log entry for the specified user with the specified tags and payload. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID tags List [] 0 ~ 20 items Tags Key-value pairs attached to the log entry for filtering and categorization. Tags enable efficient searching and aggregation of in-game logs (e.g., event type, stage ID, item category). payload string  ~ 10485760 chars Payload The custom log data in JSON format. Can contain any game-specific information such as player actions, game state, or business metrics. Maximum 10MB. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item InGameLog In-game log Implementation Example queryAccessLogWithTelemetry Get a list of access logs with telemetry Queries access logs that include telemetry data within the specified time range, with optional filtering by user ID. Telemetry data provides additional performance and diagnostic information for each API call. When searching periods longer than 7 days, the longTerm flag must be enabled. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time longTerm bool false Search logs for periods longer than 7 days 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Access Logs nextPageToken string Page token to retrieve the rest of the listing totalCount long Total number of query results scanSize long Total bytes scanned during search Implementation Example describeInsights Get a list of insights Retrieves a paginated list of GS2-Insight instances for the specified namespace. Each insight represents a log analysis environment that can be started and automatically shuts down after 2 hours. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of GS2-Insights nextPageToken string Page token to retrieve the rest of the listing Implementation Example createInsight Create insight Starts a new GS2-Insight log analysis environment for the specified namespace. The insight instance will automatically shut down after 2 hours of uptime. Only one instance can be active per namespace at a time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Insight GS2-Insight Implementation Example getInsight Get GS2-Insight Retrieves the specified GS2-Insight instance, including its current status and startup time. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). insightName string  UUID ~ 36 chars Name Result Type Description item Insight GS2-Insight Implementation Example deleteInsight Delete a insight Deletes the specified GS2-Insight instance, shutting down the log analysis environment immediately. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). insightName string  UUID ~ 36 chars Name Result Type Description item Insight GS2-Insight Implementation Example describeDashboards Get list of dashboards Retrieves a paginated list of dashboards for the specified namespace. Dashboards provide customizable views for visualizing log data and metrics. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by namespace name prefix 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 List of Dashboards nextPageToken string Page token to retrieve the rest of the listing Implementation Example createDashboard Create new dashboard Creates a new dashboard with the specified display name and description. The dashboard payload (layout and widget configuration) can be set later via update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayName string  ~ 256 chars Display Name A human-readable name for this dashboard, shown in the dashboard list and header. description string ~ 1024 chars Description Result Type Description item Dashboard Created Dashboard Implementation Example getDashboard Get Dashboard Retrieves the specified dashboard, including its display name, description, and payload configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dashboardName string  UUID ~ 36 chars Dashboard Name Result Type Description item Dashboard Dashboard Implementation Example updateDashboard Update Dashboard Updates the specified dashboard’s display name, description, and/or payload configuration. The payload contains the dashboard layout and widget definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dashboardName string  UUID ~ 36 chars Dashboard Name displayName string  ~ 256 chars Display Name A human-readable name for this dashboard, shown in the dashboard list and header. description string ~ 1024 chars Description payload string  ~ 1048576 chars Payload The dashboard configuration in JSON format, containing widget definitions, layout information, query settings, and visualization options. Result Type Description item Dashboard Updated Dashboard Implementation Example duplicateDashboard Duplicate Dashboard Creates a copy of the specified dashboard with all its configuration, including the payload (layout and widget definitions). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dashboardName string  UUID ~ 36 chars Dashboard Name Result Type Description item Dashboard Created Dashboard Implementation Example deleteDashboard Delete Dashboard Deletes the specified dashboard and all its configuration permanently. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). dashboardName string  UUID ~ 36 chars Dashboard Name Result Type Description item Dashboard Deleted Dashboard Implementation Example describeFacetModels Get list of facet models Retrieves a paginated list of facet models for the specified namespace. Facet models define custom classification fields for log queries, specifying the field name, type (string or measure), display name, and sort order. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by namespace name prefix 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 List of Facet Models nextPageToken string Page token to retrieve the rest of the listing Implementation Example createFacetModel Create new facet model Creates a new facet model with the specified field name, type, display name, and sort order. The field type can be ‘string’ for categorical classification or ‘measure’ for numeric aggregation in log queries. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). type string (enum) enum {   “string”,   “double”,   “measure” }  Facet Data Type The data type of the facet field. “string” for categorical values with value counts, “double” for numeric values with range filtering, “measure” for measurement values with statistical analysis. Definition Description “string” String “double” Double “measure” Measure displayName string  ~ 128 chars Display Name A human-readable name for this facet, shown in the log search UI. order int 0 0 ~ 100000 Display Order The sort order for displaying this facet in the UI. Lower values appear first. Result Type Description item FacetModel Created Facet Model Implementation Example getFacetModel Get Facet Model Retrieves the specified facet model, including its field name, type, display name, and sort order. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). Result Type Description item FacetModel Facet Model Implementation Example updateFacetModel Update Facet Model Updates the specified facet model’s type, display name, and/or sort order. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). type string (enum) enum {   “string”,   “double”,   “measure” }  Facet Data Type The data type of the facet field. “string” for categorical values with value counts, “double” for numeric values with range filtering, “measure” for measurement values with statistical analysis. Definition Description “string” String “double” Double “measure” Measure displayName string  ~ 128 chars Display Name A human-readable name for this facet, shown in the log search UI. order int 0 0 ~ 100000 Display Order The sort order for displaying this facet in the UI. Lower values appear first. Result Type Description item FacetModel Updated Facet Model Implementation Example deleteFacetModel Delete Facet Model Deletes the specified facet model. Deleted facet models will no longer be available for classification in log queries. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). Result Type Description item FacetModel Deleted Facet Model Implementation Example queryMetricsTimeseries Time Series Query (Metrics) Queries time series data from metrics with configurable aggregation, grouping, and interval. Supports multiple aggregation configurations, groupBy labels for multi-dimensional analysis, and sorting by value or name in ascending/descending order. The maximum number of data points is 1500; requests exceeding this limit will be rejected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time query string ~ 10240 chars Search query string groupBy List [] 0 ~ 10 items Fields to group by aggregations List [] 0 ~ 10 items List of aggregation configurations interval int 60000 1000 ~ 86400000 Aggregation interval in milliseconds seriesLimit int 10 1 ~ 1000 Number of series to retrieve orderKey string (enum) enum {   “value”,   “name” } “value” Order key Definition Description “value” Value “name” Name orderBy string (enum) enum {   “asc”,   “desc” } “desc” Order by Definition Description “asc” Ascending “desc” Descending Result Type Description items List List of Time Series Values timeseriesMetadata TimeseriesMetadata Metadata of Time Series Implementation Example describeMetrics Get list of metrics Retrieves a paginated list of available metric models for the specified namespace. Metric models define the built-in metrics that can be queried via the time series API. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by namespace name prefix 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 List of Metric Models nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeLabelValues Get list of label values for a specific metric Retrieves the available label values for a specific metric. Label values can be used as groupBy fields or filters in time series queries. Can optionally filter by label name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metricName string  ~ 128 chars Metric name to filter by labelNamePrefix string ~ 64 chars Filter by label name prefix 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 List of Label Values nextPageToken string Page token to retrieve the rest of the listing Implementation Example queryLog Query log entries (v2) Queries log entries using the v2 log query API with optional full-text search. Supports query string filtering and returns a total entry count (capped at 10001 if exceeding 10000). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time query string ~ 10240 chars Search query string 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 List of Access Logs totalEntryCount int Total number of query results (returns 10001 if it exceeds 10000) nextPageToken string Page token to retrieve the rest of the listing Implementation Example getLog Get a single log entry by request ID Retrieves a specific log entry by its request ID within the specified time range. The request ID uniquely identifies a single API call log entry. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). logRequestId string  ~ 128 chars Request ID begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time Result Type Description item LogEntry Access Log Implementation Example queryFacets Facet Query Retrieves facet (classification) data for log entries within the specified time range. Returns both built-in facets (service, function, status, duration) and custom facet models defined for the namespace. Supports query string filtering to narrow down the facet scope. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time query string ~ 10240 chars Search query string Result Type Description items List List of Facets Implementation Example queryTimeseries Time Series Query (Log) Queries time series data from log entries with configurable aggregation, grouping, and interval. Supports groupBy fields for multi-dimensional analysis and a single aggregation configuration. The maximum number of data points is 1500; requests exceeding this limit will be rejected. Results can be paginated and the number of series can be limited. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time query string ~ 10240 chars Search query string groupBy List [] 0 ~ 10 items Fields to group by aggregation AggregationConfig  Aggregation configuration interval int 60000 1000 ~ 86400000 Aggregation interval in milliseconds seriesLimit int 10 1 ~ 1000 Number of series to retrieve 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 List of Time Series Values timeseriesMetadata TimeseriesMetadata Metadata of Time Series nextPageToken string Page token to retrieve the rest of the listing Implementation Example getTrace Get trace by trace ID Retrieves a trace and its associated log entries by trace ID within the specified time range. Returns the main trace along with any parallel traces that were executed concurrently, with a flag indicating if the parallel list was truncated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). traceId string  UUID ~ 36 chars Trace ID A unique identifier for this trace, shared across all related log entries (spans) in the request flow. begin long The absolute time 1 hour prior to the current time Search range start date and time end long Current time Search range end date and time Result Type Description trace Trace Trace parallels List List of traces that were run in parallel parallelTruncated bool Indicates if the parallels list was truncated Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Log SDK for various programming languages\n","title":"GS2-Log SDK API Reference","url":"/api_reference/log/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for how reward transactions are executed within this namespace. receiveScript ScriptSetting Script to run when receiving rewards Script Trigger Reference - receive logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, login bonus operations (receive, missed recovery, etc.) are logged for monitoring and analysis. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting GitHub Checkout Setting Configuration for fetching master data directly from a GitHub repository. Allows specifying a repository, file path, and source reference (commit hash, branch, or tag) to automatically retrieve and apply master data JSON files. Requires a GS2-Key GitHub API Key for authentication with the GitHub API. Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” ReceiveStatus Receive Status Tracks the login bonus receive status for each user per bonus model. Maintains a boolean array (receivedSteps) where each entry indicates whether the user has received the corresponding day’s reward. Also records the last time a bonus was received (lastReceivedAt) to determine daily eligibility. The receivedSteps can be reset when the bonus cycle restarts (e.g., in Streaming Mode with repeat enabled). Details  receiveStatusId string * ~ 1024 chars Receive status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID receivedSteps List [] 0 ~ 100 items Received Steps An ordered boolean array where each element corresponds to a day in the reward list. true indicates the user has received that day’s reward; false indicates it was missed or not yet received. The array index aligns with the rewards array in the associated BonusModel. In Streaming Mode with repeat enabled, this array is reset when the cycle restarts. lastReceivedAt long Last Received At The timestamp of when the user last received a login bonus. Used to determine whether the user has already received today’s bonus based on the reset hour defined in the bonus model. Reset to 0 when the receive status is cleared (e.g., on cycle restart in repeat mode). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision BonusModel Login Bonus Model Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days. Details  bonusModelId string * ~ 1024 chars Login Bonus Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Login Bonus Model name Login Bonus 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. resetHour int {periodEventId} == \"\"  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Reward Reward Represents a single day’s reward configuration for a login bonus. Each Reward contains a list of acquire actions that define what the user receives (e.g., items, currency, experience). The rewards array in BonusModel holds one Reward per day, distributed in order. Reward values can be modified at runtime through the buff system (BonusModelBuff) to apply rate multipliers to acquire actions. Details  acquireActions List  1 ~ 10 items List of Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies an acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. ConsumeAction Consume Action Defines an action for consuming resources from a user via the transaction mechanism. Used in missed-bonus recovery to specify the cost users must pay (e.g., deducting currency, consuming items). The action field specifies the type of consume action, and the request field contains the corresponding request parameters. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action Defines an action for granting resources to a user via the transaction mechanism. Used within rewards to specify what the user receives (e.g., adding items to inventory, granting currency, awarding experience points). The action field specifies the type of acquire action, and the request field contains the corresponding request parameters. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters. Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration A key-value pair used to set values applied to transaction variables. Config entries allow dynamic parameterization of acquire actions at runtime. For example, slot names or other context-dependent values can be injected into transaction requests via Config settings, enabling flexible reward configuration without modifying the master data. Details  key string  ~ 64 chars Key The variable name to be replaced in transaction parameters. Maximum 64 characters. value string ~ 51200 chars Value The value to substitute for the corresponding key in transaction parameters. Maximum 51,200 characters. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentBonusMaster Currently active Login Bonus Model master data This master data defines the Login Bonus Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-LoginReward Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data BonusModelMaster Login Bonus Model Master Login Bonus Model Master is data used to edit and manage Login Bonus Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Login Bonus Model actually referenced by the game. A Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days. Details  bonusModelId string * ~ 1024 chars Login Reward Model Master Data A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. resetHour int {periodEventId} == \"”  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for how reward transactions are executed within this namespace. receiveScript ScriptSetting Script to run when receiving rewards Script Trigger Reference - receive logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, login bonus operations (receive, missed recovery, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for how reward transactions are executed within this namespace. receiveScript ScriptSetting Script to run when receiving rewards Script Trigger Reference - receive logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, login bonus operations (receive, missed recovery, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example receive Get login rewards Receives the login bonus for the requesting user based on the specified bonus model. The bonus progresses through steps, and the current step’s reward is issued as a transaction. If the reward cycle has been completed and repeat is enabled, the cycle resets automatically. If the bonus has already been received for the current period, an AlreadyReceived error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item ReceiveStatus Receive status bonusModel BonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example receiveByUserId Get login rewards by userId Receives the login bonus for the specified user based on the bonus model. The bonus progresses through steps, and the current step’s reward is issued as a transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus Receive status bonusModel BonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example missedReceive Receive missed login rewards Receives a previously missed login bonus for the requesting user. The missed receive relief feature must be enabled on the bonus model. In CUMULATIVE mode, the step number can be auto-calculated; in SCHEDULE mode, the step number must be specified. The missed reward is issued as a transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token stepNumber int 0 ~ 100 Step number to receive. In streaming mode, this can be omitted config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item ReceiveStatus Receive status bonusModel BonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example missedReceiveByUserId Receive missed login rewards by userId Receives a previously missed login bonus for the specified user. The missed receive relief feature must be enabled on the bonus model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID stepNumber int 0 ~ 100 Step number to receive. In streaming mode, this can be omitted config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus Receive status bonusModel BonusModel Login Bonus Model transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the receipt of login bonuses stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeReceiveStatuses Get a list of received statuses Retrieves a paginated list of login bonus receive statuses for the requesting user. Each status tracks which steps have been received and the current progress for a specific bonus model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of ReceiveStatuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeReceiveStatusesByUserId Get a list of received statuses by specifying a user ID Retrieves a paginated list of login bonus receive statuses for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of ReceiveStatuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example getReceiveStatus Get Receive Status Retrieves the receive status for the requesting user’s specified bonus model. Returns the current step progress, received steps, and the associated bonus model details. If the reward cycle is complete and repeat is enabled, the status is automatically reset. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. accessToken string  ~ 128 chars Access token Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example getReceiveStatusByUserId Get Receive Status by specifying a user ID Retrieves the receive status for the specified user’s bonus model, including step progress and received steps. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example deleteReceiveStatusByUserId Delete Receive Status by specifying a user ID Deletes all receive status data for the specified user’s bonus model, completely resetting the bonus progress. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example markReceived Mark as received Manually marks a specific step as received for the requesting user’s bonus model. Updates the received steps bit array. If the specified step has already been received, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. accessToken string  ~ 128 chars Access token stepNumber int  0 ~ 100 Step Number Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example markReceivedByUserId Mark as received by specifying a user ID Manually marks a specific step as received for the specified user’s bonus model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID stepNumber int  0 ~ 100 Step Number timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example unmarkReceivedByUserId Unmark as received by specifying a user ID Reverses a previously marked step back to unreceived for the specified user’s bonus model. If the specified step was not marked as received, an error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID stepNumber int  0 ~ 100 Step Number timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ReceiveStatus ReceiveStatus bonusModel BonusModel Login Bonus Model Implementation Example describeBonusModels Get a list of Login Bonus Models Retrieves the list of currently active login bonus models for the specified namespace. The models define the bonus mode (CUMULATIVE or SCHEDULE), reset timing, repeat settings, and reward sequences. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Login Bonus Models Implementation Example getBonusModel Get Login Bonus Model Retrieves the specified login bonus model, including its mode, reset timing, repeat settings, reward list, and missed receive relief configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BonusModel Login Bonus Model Implementation Example exportMaster Export Login Bonus Model Master in a master data format that can be activated Exports the currently active login bonus model masters in a format suitable for activation. The exported data can be used to update master data in another namespace or stored as a backup. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentBonusMaster Login Bonus Model master data that can be activated Implementation Example getCurrentBonusMaster Get currently active Login Bonus Model master data Retrieves the currently active login bonus model master data for the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentBonusMaster Currently active Login Bonus Model master data Implementation Example preUpdateCurrentBonusMaster Update currently active Login Bonus Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentBonusMaster Update currently active Login Bonus Model master data Updates the currently active login bonus model master data. Supports two modes: ‘direct’ for inline settings, and ‘preUpload’ for applying settings previously uploaded via the 3-phase update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentBonusMaster Updated master data of the currently active Login Bonus Models Implementation Example updateCurrentBonusMasterFromGitHub Update currently active Login Bonus Model master data from GitHub Updates the currently active login bonus model master data by fetching it from a specified GitHub repository. The API key stored in GS2-Key is used for authentication, and you can specify the branch, tag, or commit hash to checkout. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentBonusMaster Updated master data of the currently active Login Bonus Models Implementation Example describeBonusModelMasters Get a list of Login Bonus Model Masters Retrieves a paginated list of login bonus model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Login Bonus Model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Login Bonus Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createBonusModelMaster Create a new Login Bonus Model Master Creates a new login bonus model master with the specified configuration. The mode can be CUMULATIVE (sequential daily bonuses) or SCHEDULE (event-period-based bonuses). You can configure reset hour, repeat behavior, reward sequences, and missed receive relief with optional verify/consume actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN resetHour int {periodEventId} == \"”  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Result Type Description item BonusModelMaster Created Login Bonus Model Master Implementation Example getBonusModelMaster Get Login Bonus Model Master Retrieves the specified login bonus model master, including its mode, reset timing, repeat settings, reward list, and missed receive relief configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BonusModelMaster Login Bonus Model Master Implementation Example updateBonusModelMaster Update Login Bonus Model Master Updates the specified login bonus model master. You can modify the description, metadata, mode, reset timing, repeat settings, reward sequences, and missed receive relief configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN resetHour int {periodEventId} == \"”  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Result Type Description item BonusModelMaster Login Bonus Model Master updated Implementation Example deleteBonusModelMaster Delete Login Bonus Model Master Deletes the specified login bonus model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Login Bonus Model name Login Bonus Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item BonusModelMaster Login Bonus Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-LoginReward SDK for various programming languages\n","title":"GS2-LoginReward SDK API Reference","url":"/api_reference/login_reward/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing lottery operations. Lottery draws issue transactions that grant prizes to users via acquire actions. lotteryTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be called when the lottery is executed Script Trigger Reference - lottery logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of lottery operations. Useful for tracking draw results, prize distributions, and box gacha states for debugging and analytics. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” PrizeTable Prize Table A prize can either specify an acquire action directly or reference another Prize Table. By nesting Prize Tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game. Details  prizeTableId string * ~ 1024 chars Prize Table A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. Probability Draw Probability Represents the calculated draw probability for a specific prize. The rate is computed from the prize’s weight relative to the total weight of all prizes in the Prize Table. For box gacha, the probability changes dynamically as prizes are drawn from the box. Details  prize DrawnPrize  Prize The prize that this probability corresponds to, including its ID and acquire actions. rate float  0 ~ 1.0 Draw Probability (0.0-1.0) The probability of drawing this prize, expressed as a value between 0.0 and 1.0. Calculated as this prize’s weight divided by the total weight of all prizes in the table. PrizeLimit Prize Limit Tracks the number of times a specific prize has been drawn across all users. When the drawn count reaches the maximum defined in the Prize’s drawnLimit, the failover prize is drawn instead. Used to implement limited-quantity prizes such as rare jackpot items. Details  prizeLimitId string * ~ 1024 chars Prize Limit A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server prizeId string  ~ 36 chars Prize ID The ID of the prize whose draw count is being tracked. drawnCount int  0 ~ 2147483646 Drawn Count The current number of times this prize has been drawn across all users. Compared against the Prize’s drawnLimit to determine if the failover prize should be used. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision DrawnPrize Drawn Prize Represents a prize that has been drawn from the lottery. Contains the prize ID and the acquire actions that were executed to grant the prize to the user. Details  prizeId string  ~ 36 chars Prize ID The ID of the drawn prize, corresponding to a prize entry in the Prize Table. acquireActions List 0 ~ 100 items List of Acquire Actions The list of acquire actions executed to grant this prize to the user. BoxItems Box Items Records the state of a box gacha for a specific user and Prize Table. Contains the list of all prizes in the box along with their remaining and initial quantities, allowing the user to see which prizes have been drawn and which remain. Details  boxId string * ~ 1024 chars Box A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server prizeTableName string  ~ 128 chars Prize Table name The name of the Prize Table associated with this box. Identifies which box gacha this record belongs to. userId string  ~ 128 chars User ID items List [] 0 ~ 1000 items Items The list of all prizes in the box with their remaining and initial quantities. Each item shows how many of that prize were originally in the box and how many remain, allowing tracking of the box gacha’s draw progress. LotteryModel Lottery Model Lottery Model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha. Details  lotteryModelId string * ~ 1024 chars Lottery Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios like applying a different Prize Table for one draw in a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table Script Trigger Reference - choicePrizeTable * Required if method is “script” Prize Prize A single prize entry within a Prize Table. A prize can either directly specify acquire actions (granting items, currency, etc.) or reference another Prize Table to perform a nested draw. Each prize has a draw weight that determines its relative probability of being drawn. Details  prizeId string  UUID ~ 36 chars Prize ID A unique identifier for this prize within the Prize Table. Used to track draw limits and as a reference when specifying failover prizes. type string (enum) enum {   “action”,   “prize_table” }  Prize Type Determines whether this prize directly grants rewards or delegates to another Prize Table. “action” specifies acquire actions to execute when drawn. “prize_table” references another Prize Table for a nested drawing (e.g., first draw determines rarity, second draw determines specific item). Definition Description “action” Acquire Actions for the prize “prize_table” Delegates the draw to another Prize Table (performs a nested draw). acquireActions List {type} == “action” [] 1 ~ 100 items List of Acquire Actions The list of acquire actions to execute when this prize is drawn. Multiple actions can be specified to grant several rewards at once (e.g., an item and currency together). * Enabled only if type is “action” drawnLimit int {type} == “action” 1 ~ 1000000 Maximum Number of Draws The maximum number of times this prize can be drawn across all users. When the limit is reached, the failover prize (limitFailOverPrizeId) is drawn instead. Used to implement limited-quantity prizes such as jackpot items. * Enabled only if type is “action” limitFailOverPrizeId string {type} == “action” and {drawnLimit} \u003e 0  ~ 32 chars Limit Failover Prize ID The ID of the prize to draw instead when this prize’s draw limit (drawnLimit) has been reached. Must reference another prize within the same Prize Table. * Required if type is “action” and drawnLimit is greater than 0 prizeTableName string {type} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to delegate the draw to. Used when the prize type is “prize_table” for nested drawing. * Required if type is “prize_table” weight int  1 ~ 2147483646 Draw Weight The relative weight of this prize in the Prize Table. The actual draw probability is calculated as this prize’s weight divided by the total weight of all prizes in the table. For example, if three prizes have weights of 70, 20, and 10, their draw probabilities are 70%, 20%, and 10% respectively. BoxItem Box Item Represents a single prize type within a box gacha, showing its initial quantity in the box, remaining quantity, and the acquire actions that will be executed when drawn. Details  prizeId string  ~ 128 chars Prize ID The ID of the prize in the Prize Table that this box item corresponds to. acquireActions List [] 0 ~ 100 items List of Acquire Actions The list of acquire actions to execute when this prize is drawn from the box. remaining int  0 ~ 2147483646 Remaining Quantity The number of this prize still remaining in the box. Decreases by one each time this prize is drawn. initial int  0 ~ 2147483646 Initial Quantity The number of this prize that was originally placed in the box. Used together with remaining to calculate how many have been drawn. AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentLotteryMaster Currently active Lottery Model master data This master data defines the Lottery Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Lottery Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data LotteryModelMaster Lottery Model Master Lottery Model Master is data used to edit and manage Lottery Models within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Lottery Model actually referenced by the game. Lottery Model is the entity that defines the draw method and draw rate. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha. GS2-Script can be used to dynamically select the Prize Table at draw time, enabling scenarios such as applying a different Prize Table only once in a multi-draw (e.g., 10-draw gacha). Details  lotteryModelId string * ~ 1024 chars Lottery Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. description string ~ 1024 chars Description mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios such as applying a different drop probability table just once during a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table Script Trigger Reference - choicePrizeTable * Required if method is “script” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision PrizeTableMaster Prize Table Master Prize Table Master is data used to edit and manage Prize Table within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Prize Table actually referenced by the game. A prize can either specify an acquire action directly or reference another Prize Table. By nesting Prize Tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game. Details  prizeTableId string * ~ 1024 chars Prize Table Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Prize Table Name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing lottery operations. Lottery draws issue transactions that grant prizes to users via acquire actions. lotteryTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be called when the lottery is executed logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of lottery operations. Useful for tracking draw results, prize distributions, and box gacha states for debugging and analytics. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing lottery operations. Lottery draws issue transactions that grant prizes to users via acquire actions. lotteryTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be called when the lottery is executed logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of lottery operations. Useful for tracking draw results, prize distributions, and box gacha states for debugging and analytics. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describePrizeTables Get a list of Prize Tables Retrieves the list of currently active Prize Tables for the specified namespace. Prize Tables define the prizes and their draw probabilities or weights used by lottery models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Prize Tables Implementation Example getPrizeTable Get Prize Table Retrieves the specified Prize Table, including its list of prizes with their draw probabilities, weights, and quantity limits. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PrizeTable Prize Table Implementation Example drawByUserId Execute a lottery by specifying a User ID Performs a lottery draw for the specified user based on the lottery model configuration. The lottery supports two methods: Prize Table mode (using predefined probability tables) and Script mode (using a GS2-Script to determine prizes). In box lottery mode, drawn prizes are removed from the box and cannot be drawn again. If the box is empty, an Empty error is returned. The drawn prizes are issued as a transaction. Details Request  namespaceName string  ~ 128 chars Namespace name lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). userId string  ~ 128 chars User ID count int  1 ~ 1000 Number of draws config List [] 0 ~ 1000 items Configuration values applied to transaction placeholders timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Prize emission boxItems BoxItems List of items taken out of the box transactionId string Issued transaction ID stampSheet string Stamp sheet to obtain emission prizes stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example prediction Get the prediction result of the lottery result Predicts lottery outcomes without actually awarding prizes or generating transactions. Uses a random seed for deterministic results, allowing the same prediction to be reproduced with the same seed. This is useful for showing players what they would receive before committing to the draw. Details Request  namespaceName string  ~ 128 chars Namespace name lotteryName string  ~ 128 chars Lottery Model name accessToken string  ~ 128 chars Access token randomSeed long  0 ~ 9223372036854775805 Random seed count int  1 ~ 1000 Number of draws Result Type Description items List List of Prize emission Implementation Example predictionByUserId Get the prediction result of the lottery result by specifying a user ID Predicts lottery outcomes for the specified user without awarding prizes or generating transactions. Uses a random seed for deterministic results. Details Request  namespaceName string  ~ 128 chars Namespace name lotteryName string  ~ 128 chars Lottery Model name userId string  ~ 128 chars User ID randomSeed long  0 ~ 9223372036854775805 Random seed count int  1 ~ 1000 Number of draws timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Prize emission Implementation Example drawWithRandomSeedByUserId Execute a lottery with a random seed by specifying a user ID Performs a deterministic lottery draw using the specified random seed. The random seed is offset by the iteration count for each draw, ensuring unique but reproducible results. This method is incompatible with box lottery mode. The drawn prizes are issued as a transaction. Details Request  namespaceName string  ~ 128 chars Namespace name lotteryName string  ~ 128 chars Lottery Model name userId string  ~ 128 chars User ID randomSeed long  0 ~ 9223372036854775805 Random seed count int  1 ~ 1000 Number of draws config List [] 0 ~ 1000 items Configuration values applied to transaction placeholders timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Prize emission transactionId string Issued transaction ID stampSheet string Stamp sheet to obtain emission prizes stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeProbabilities Get a list of Draw Probabilities The normal lottery responds with the same probability for all game players. The box draw responds with a different probability for each game player, taking into account the remaining contents of the box. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of draw probabilities Implementation Example describeProbabilitiesByUserId Get a list of Draw Probabilities by specifying a user ID The normal lottery responds with the same probability for all game players. The box draw responds with a different probability for each game player, taking into account the remaining contents of the box. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of draw probabilities Implementation Example describePrizeLimits Get a list of Prize Limits Retrieves a paginated list of prize draw count limits for the specified Prize Table. Prize limits track how many times each prize has been drawn, enabling limited-quantity prize configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name Prize Table-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 List of Prize Limits nextPageToken string Page token to retrieve the rest of the listing Implementation Example getPrizeLimit Get Prize Limit Retrieves the current draw count for a specific prize in the Prize Table. This shows how many times the prize has been drawn against its configured limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeId string  UUID ~ 36 chars Prize ID A unique identifier for this prize within the Prize Table. Used to track draw limits and as a reference when specifying failover prizes. Result Type Description item PrizeLimit Prize Limit Implementation Example resetPrizeLimit Reset Prize Limit Resets the draw count for a specific prize by deleting the prize limit record. After reset, the prize becomes available for drawing again up to its configured limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeId string  UUID ~ 36 chars Prize ID A unique identifier for this prize within the Prize Table. Used to track draw limits and as a reference when specifying failover prizes. Result Type Description Implementation Example describeBoxes Get a list of items extracted from the box Retrieves a paginated list of box states for all box-mode lottery models in the namespace. Each entry shows which prizes have been drawn from the box and their remaining quantities. If a box has not yet been drawn, an empty box state is created and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of box states nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeBoxesByUserId Get a list of boxes by specifying a user ID Retrieves a paginated list of box states for the specified user across all box-mode lottery models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of box states nextPageToken string Page token to retrieve the rest of the listing Implementation Example getBox Get Box Retrieves the box state for a specific Prize Table, showing which prizes have been drawn and their remaining quantities. If the box does not exist yet, an empty box state is created and returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name accessToken string  ~ 128 chars Access token Result Type Description item BoxItems Box state including prizes and their remaining quantities Implementation Example getBoxByUserId Get Box by specifying a user ID Retrieves the box state for a specific Prize Table and user, showing drawn prizes and remaining quantities. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BoxItems Box state including prizes and their remaining quantities Implementation Example resetBox Reset Box Resets the box to its initial state, returning all drawn prizes back into the box. After reset, all prizes become available for drawing again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name accessToken string  ~ 128 chars Access token Result Type Description item BoxItems Box state including prizes and their initial quantities Implementation Example resetBoxByUserId Reset box with specified user ID Resets the specified user’s box to its initial state, returning all drawn prizes back into the box. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item BoxItems Box state including prizes and their initial quantities Implementation Example describeLotteryModels Get a list of Lottery Models Retrieves the list of currently active lottery models for the specified namespace. The models define the lottery mode (normal or box), draw method (Prize Table or script), and associated Prize Table configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Lottery Model Implementation Example getLotteryModel Get Lottery Model Retrieves the specified lottery model, including its mode (normal/box), draw method (Prize Table/script), and Prize Table name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item LotteryModel Lottery Model Implementation Example exportMaster Export Lottery Model Master in a master data format that can be activated Exports the currently active lottery model masters in a format suitable for activation. The exported data can be used to update master data in another namespace or stored as a backup. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentLotteryMaster Lottery Model master data that can be activated Implementation Example getCurrentLotteryMaster Get currently active Lottery Model master data Retrieves the currently active lottery model master data for the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentLotteryMaster Currently Active Lottery Model Master Data Implementation Example preUpdateCurrentLotteryMaster Update Currently Active Lottery Model Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentLotteryMaster Update Currently Active Lottery Model Master Data Updates the currently active lottery model master data. Supports two modes: ‘direct’ for inline settings, and ‘preUpload’ for applying settings previously uploaded via the 3-phase update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentLotteryMaster Updated current active Lottery Model master data Implementation Example updateCurrentLotteryMasterFromGitHub Update Currently Active Lottery Model Master Data from GitHub Updates the currently active lottery model master data by fetching it from a specified GitHub repository. The API key stored in GS2-Key is used for authentication, and you can specify the branch, tag, or commit hash to checkout. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentLotteryMaster Updated current active Lottery Model master data Implementation Example describeLotteryModelMasters Get a list of Lottery Model Masters Retrieves a paginated list of lottery model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Lottery Model name prefix 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 List of Lottery Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createLotteryModelMaster Create a new Lottery Model Master Creates a new lottery model master with the specified configuration. The mode can be ’normal’ (standard lottery with replacement) or ‘box’ (lottery without replacement where drawn prizes are removed from the pool). The method can be ‘prizeTable’ (using a predefined Prize Table) or ‘script’ (using a GS2-Script to determine prizes dynamically). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios such as applying a different drop probability table just once during a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table * Required if method is “script” Result Type Description item LotteryModelMaster Lottery Model Master created Implementation Example getLotteryModelMaster Get Lottery Model Master Retrieves the specified lottery model master, including its mode (normal/box), draw method (prizeTable/script), and associated Prize Table or script configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item LotteryModelMaster Lottery Model Master Implementation Example updateLotteryModelMaster Update Lottery Model Master Updates the specified lottery model master. You can modify the description, metadata, mode (normal/box), draw method (prizeTable/script), Prize Table name, and script settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). description string ~ 1024 chars Description 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios such as applying a different drop probability table just once during a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table * Required if method is “script” Result Type Description item LotteryModelMaster Lottery Model Master updated Implementation Example deleteLotteryModelMaster Delete Lottery Model Master Deletes the specified lottery model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). Result Type Description item LotteryModelMaster Lottery Model Master deleted Implementation Example describePrizeTableMasters Get a list of Prize Table Masters Retrieves a paginated list of Prize Table masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Prize Table name prefix 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 List of Prize Tables nextPageToken string Page token to retrieve the rest of the listing Implementation Example createPrizeTableMaster Create a new Prize Table Master Creates a new Prize Table Master with the specified prizes configuration. Each prize entry defines the prize ID, type, acquire actions, draw weight, and optional quantity limit. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Prize Table Name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. Result Type Description item PrizeTableMaster Prize Table Master created Implementation Example getPrizeTableMaster Get Prize Table Master Retrieves the specified Prize Table Master, including its list of prizes with their draw weights, types, and quantity limits. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table Name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PrizeTableMaster Prize Table Master Implementation Example updatePrizeTableMaster Update Prize Table Master Updates the specified Prize Table Master. You can modify the description, metadata, and the list of prizes with their draw weights and quantity limits. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table Name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. Result Type Description item PrizeTableMaster Prize Table Master updated Implementation Example deletePrizeTableMaster Delete Prize Table Master Deletes the specified Prize Table Master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table Name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item PrizeTableMaster Prize Table Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Lottery SDK for various programming languages\n","title":"GS2-Lottery SDK API Reference","url":"/api_reference/lottery/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing matchmaking operations. enableRating bool false Enable Rating Whether to enable the Glicko-2 based rating calculation function. When enabled, players can submit match results via the Vote system and have their ratings automatically updated. Requires RatingModel master data to be configured. Defaults to false. enableDisconnectDetection string (enum) enum {   “disable”,   “enable” } “disable” Disconnect Detection Controls whether players in matchmaking must periodically report they are still waiting. When enabled, if a player does not send a keep-alive within the configured timeout period, they are automatically removed from the Gathering. This prevents “ghost” players from blocking matchmaking completion. Defaults to “disable”. Definition Description “disable” Disable “enable” Enable disconnectDetectionTimeoutSeconds int {enableDisconnectDetection} == “enable”  15 ~ 600 Disconnect Detection Timeout (seconds) The number of seconds to wait without a keep-alive report before a player is considered disconnected and removed from the Gathering. Only applies when disconnect detection is enabled. Must be between 15 and 600 seconds. * Required if enableDisconnectDetection is “enable” createGatheringTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Create Gathering Trigger Type The type of action to execute when a new Gathering is created. Can trigger GS2-Realtime room creation for real-time communication, or execute a GS2-Script for custom logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution createGatheringTriggerRealtimeNamespaceId string {createGatheringTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace to create rooms when creating a gathering * Required if createGatheringTriggerType is “gs2_realtime” createGatheringTriggerScriptId string {createGatheringTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when creating a gathering Script Trigger Reference - createGathering * Required if createGatheringTriggerType is “gs2_script” completeMatchmakingTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Complete Matchmaking Trigger Type The type of action to execute when matchmaking completes (all role slots are filled). Can trigger GS2-Realtime room creation for the matched players, or execute a GS2-Script for custom post-match logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution completeMatchmakingTriggerRealtimeNamespaceId string {completeMatchmakingTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to create rooms when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_realtime” completeMatchmakingTriggerScriptId string {completeMatchmakingTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when matchmaking is complete Script Trigger Reference - completeMatchmaking * Required if completeMatchmakingTriggerType is “gs2_script” enableCollaborateSeasonRating string (enum) enum {   “enable”,   “disable” } “disable” Enable Season Rating Collaboration Whether to enable integration with GS2-SeasonRating for season-based rating calculations. When enabled, a rating calculation session is automatically created in the specified GS2-SeasonRating namespace when matchmaking completes. Defaults to “disable”. Definition Description “enable” Enable “disable” Disable collaborateSeasonRatingNamespaceId string {enableCollaborateSeasonRating} == “enable”  ~ 1024 chars Season Rating Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-SeasonRating namespace where rating calculation sessions are created when matchmaking completes. Only applicable when Season Rating collaboration is enabled. * Required if enableCollaborateSeasonRating is “enable” collaborateSeasonRatingTtl int {enableCollaborateSeasonRating} == “enable” 60 60 ~ 7200 Season Rating Result TTL (seconds) The maximum time in seconds to wait for match result submissions via GS2-SeasonRating after matchmaking completes. If results are not submitted within this period, the rating session expires. Must be between 60 and 7200 seconds. Defaults to 60. * Enabled only if enableCollaborateSeasonRating is “enable” changeRatingScript ScriptSetting Script setting to be executed when the rating value changes Script Trigger Reference - changeRating joinNotification NotificationSetting Join Notification Push Notification Setting for when a new player joins a Gathering. Notifies existing participants that a new player has joined, allowing the game client to update the matchmaking UI. leaveNotification NotificationSetting Leave Notification Push Notification Setting for when a player leaves a Gathering. Notifies remaining participants that a player has left, allowing the game client to reflect the change. completeNotification NotificationSetting Complete Notification Push Notification Setting for when matchmaking completes (all role slots are filled). Notifies all participants that the Gathering is full and the match can begin. changeRatingNotification NotificationSetting Change Rating Notification Push Notification Setting for when a player’s rating value changes after vote processing. Notifies the affected player of their new rating, allowing the game client to display the updated value. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, matchmaking operations (create/join/leave gathering, vote, rating changes, etc.) are logged for monitoring and analysis. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Gathering Gathering An entity representing a group of game players brought together by matchmaking. It has multiple parameters for matchmaking, and the players are grouped based on the totality of the parameters. Players join a Gathering by specifying their role, attributes, and optionally a blacklist of users they do not wish to play with. Joining is validated against attribute range requirements, role capacity limits, and whitelist restrictions (allowUserIds). When all role slots are filled to capacity, the Gathering is considered complete and matchmaking finishes. Gathering names are automatically generated in UUID format, and an optional expiration time can be set for automatic cleanup. Details  gatheringId string * ~ 1024 chars Gathering A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. capacityOfRoles List [] 1 ~ 5 items List of Role Capacities Defines the recruitment slots for this Gathering. Each entry specifies a role name, its aliases, and the maximum number of players that can fill that role. When all role slots reach their capacity, matchmaking is considered complete. At least 1, maximum 5 roles. allowUserIds List [] 0 ~ 100 items Allowed User IDs A whitelist of user IDs that are permitted to join this Gathering. When specified, only the listed users can participate in matchmaking for this Gathering. Useful for friend-only or invitation-based matchmaking scenarios. Maximum 100 entries. metadata string ~ 1024 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. expiresAt long Gathering Expiration Time The time at which this Gathering automatically expires and is deleted. If matchmaking does not complete before this time, the Gathering is cleaned up. When not specified, the Gathering persists until matchmaking completes or it is manually deleted. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SeasonGathering Season Gathering A persistent gathering within a season that collects players over the season period. Unlike regular Gatherings that dissolve once matchmaking completes, Season Gatherings persist throughout the season and accumulate participants. Players are grouped by tier (based on GS2-Experience rank) and season number, and each Season Gathering has a maximum participant limit defined by the SeasonModel. Details  seasonGatheringId string * ~ 1024 chars Season Gathering A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. name string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). participants List [] 0 ~ 1000 items List of Participant User IDs The list of user IDs of players who have joined this Season Gathering. Players are added to this list when they join and the list grows throughout the season until the maximum participant limit is reached. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision JoinedSeasonGathering Joined Season Gathering A record that tracks which Season Gathering a player has joined within a specific season and tier. Created automatically when a player joins a Season Gathering, serving as an index to quickly look up the player’s current gathering. Each player can belong to at most one Season Gathering per season and tier combination. Details  joinedSeasonGatheringId string * ~ 1024 chars Joined Season Gathering A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  ~ 128 chars Season Gathering Name The name of the Season Gathering that this player has joined. Used to reference the specific Season Gathering entity within the same season and tier. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Rating Rating An entity that holds the current rating value for each game player. Created automatically when a player first participates in rated matchmaking. The rating is calculated using the Glicko-2 algorithm, with an initial rate value and rating deviation (rd) that represents the uncertainty of the rating. The rate value converges toward the player’s true skill level as more matches are played. Details  ratingId string * ~ 1024 chars Rating A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rateValue float 1500.0 0 ~ 65535.0 Rate Value The player’s current rating score calculated by the Glicko-2 algorithm. Defaults to the initial value defined in the RatingModel (typically 1500.0). The value increases or decreases based on match results and the relative strength of opponents. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Ballot Ballot A ballot paper issued to each player for reporting match results after a rated matchmaking game. Contains the context of the match: the rating model name, gathering name, and number of players. Each player receives a ballot signed by the server, which they fill in with game results and submit to the Vote API. The voting system requires more than 50% consensus among submitted ballots to finalize rating calculations. Details  userId string  ~ 128 chars User ID ratingName string  ~ 128 chars Rating Name The name of the RatingModel to use for rating calculations after this match. Identifies which rating system’s parameters (initial value, volatility) apply to this match’s result processing. gatheringName string  ~ 128 chars Gathering Name The name of the Gathering for which match results are being reported. Used to identify the specific matchmaking session and correlate votes from all participants in the same match. numberOfPlayer int  2 ~ 10 Number of Players The total number of players who participated in this match. Used to determine the expected number of ballots and validate consensus (more than 50% of players must submit matching results). Must be between 2 and 10. Vote Vote An entity that aggregates submitted ballots for a specific match to determine the final match results for rating calculation. Each Vote is identified by the combination of rating model name and gathering name. Ballots are collected from match participants, and when enough ballots with consistent results are submitted (more than 50% consensus), the vote is considered complete and the rating values of the participants are updated accordingly. Details  voteId string * ~ 1024 chars Vote A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. writtenBallots List [] 0 ~ 10 items List of Written Ballots The collection of submitted ballots from match participants. Each written ballot contains the signed ballot paper and the game results (player rankings) as reported by that participant. When more than 50% of the expected ballots contain consistent results, the vote is finalized and rating calculations proceed. Maximum 10 entries. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server RatingModel Rating Model GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value. Details  ratingModelId string * ~ 1024 chars Rating Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. SeasonModel Season Model Defines the season-specific settings for Season Matchmaking, including the period of persistent gatherings, maximum participant count, and tier integration settings. Managed by GS2-Schedule for period control, and can be linked with GS2-Experience for persistent gathering within the same tier as needed. Details  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management The GRN of the GS2-Experience experience model used to determine player tiers. The player’s rank within this experience model is used as their tier for matchmaking, ensuring players are grouped with others at a similar level. If not specified, tier-based grouping is disabled and all players are matched together regardless of level. challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Schedule event that defines the active period for this season. Season Gatherings can only be created and joined while this event is active. When the event period ends, the season closes and new matchmaking is no longer possible. AttributeRange Attribute Range A condition that defines the acceptable range of a named attribute for joining a Gathering. When a player attempts to join, their attribute value with the matching name must fall within the specified min/max range. Used to create skill-based or level-based matchmaking filters. Details  name string  ~ 128 chars Attribute Name The name of the attribute to apply this range condition to. Must match the name of an attribute in the player’s attribute list for the condition to be evaluated. min int 0 0 ~ 2147483646 Minimum Attribute Value The minimum value of the attribute required to join the Gathering (inclusive). Players whose attribute value is below this threshold cannot participate. max int 0 0 ~ 2147483646 Maximum Attribute Value The maximum value of the attribute allowed to join the Gathering (inclusive). Players whose attribute value exceeds this threshold cannot participate. CapacityOfRole Capacity of Role Defines a recruitment slot within a Gathering for a specific role. Each role has a name, optional aliases, a maximum capacity, and a list of currently participating players. Role aliases allow flexible matching: e.g., a “tank” role with aliases “paladin” and “knight” lets players specifying either sub-role fill the tank slot. When all participants in every role reach their capacity, the Gathering’s matchmaking is complete. Details  roleName string “default” ~ 128 chars Role Name The name of the role for this recruitment slot. Defaults to “default” for general matchmaking without role distinctions. For role-based matchmaking (e.g., “tank”, “healer”, “attacker”), specify the role category name here. roleAliases List [] 0 ~ 9 items List of Role Name Aliases Alternative role names that are accepted for this recruitment slot. Players specifying any of these aliases as their role name will be matched into this slot. Enables sub-role matching: e.g., “paladin” and “knight” aliases for a “tank” role. Maximum 9 aliases. capacity int  1 ~ 256 Role Capacity The maximum number of players that can fill this role slot. When the number of participants reaches this capacity, the role is considered full and no more players with this role can join. Must be between 1 and 256. participants List [] 0 ~ 1000 items List of Participant Players The list of players currently occupying this role slot. Players are added when they join the Gathering and removed when they leave. Each player entry includes their user ID, attributes, role name, and blacklist. Uniqueness is enforced by user ID. Attribute Attribute A named numeric attribute associated with a player for matchmaking purposes. Attributes are used in conjunction with AttributeRange conditions on Gatherings to filter which players can join. For example, a “level” attribute with value 50 would match a Gathering requiring level between 40 and 60. Each player can have up to 5 attributes. Details  name string  ~ 128 chars Attribute Name Attribute-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). value int 0 0 ~ 2147483646 Attribute Value The numeric value of this attribute for the player. This value is checked against the min/max range specified in the Gathering’s AttributeRange conditions during matchmaking. Player Player Represents a player participating in matchmaking, containing their identity, attributes, role, and blacklist. When joining a Gathering, a Player object is created with the player’s attribute values, desired role, and a list of users they refuse to play with. The player’s attributes are validated against the Gathering’s attribute range conditions, and their deny list is cross-checked to prevent unwanted pairings. Details  userId string  ~ 128 chars User ID attributes List [] 0 ~ 5 items List of Attributes The player’s named numeric attributes used for matchmaking condition evaluation. Each attribute is checked against the Gathering’s AttributeRange conditions to determine eligibility. The player’s own attribute values must also fall within any range conditions they set when creating a Gathering. Maximum 5 attributes. roleName string “default” ~ 128 chars Role Name The role that this player wants to fill in the Gathering. Defaults to “default” for general matchmaking without role distinctions. For role-based matchmaking, specify the player’s specific role (e.g., “paladin”, “knight”) which is matched against role names and aliases in the Gathering’s capacity definitions. denyUserIds List [] 0 ~ 100 items Deny User IDs A blacklist of user IDs that this player refuses to be matched with. During matchmaking, if any player already in the Gathering appears in this list, the player cannot join that Gathering. Conversely, if this player is in any existing participant’s deny list, joining is also blocked. Maximum 100 entries. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server GameResult Game Result Represents the result of a single player in a match, used for rating calculations via the Vote system. Each GameResult entry pairs a user ID with their rank (finishing position) in the match. Lower rank values indicate better performance (1st place = rank 1). Players with the same rank are treated as a draw. Details  rank int  0 ~ 2147483646 Rank The player’s finishing position in the match. 1 is the highest rank (winner). Used by the Glicko-2 algorithm to calculate rating changes: higher-ranked players gain rating while lower-ranked players lose rating. Players with equal ranks are treated as draws. userId string  ~ 128 chars User ID SignedBallot Signed Ballot A ballot paper with a digital signature that verifies its authenticity. The server issues signed ballots to players after matchmaking completes, ensuring that only legitimate participants can submit match results. The signature is verified when the ballot is submitted to the Vote API, preventing tampering with match context (rating name, gathering name, number of players). Details  body string  ~ 1024 chars Ballot Body The serialized ballot data that is the target of the digital signature. Contains the ballot context (user ID, rating name, gathering name, number of players) in a format that can be verified against the signature. signature string  ~ 256 chars Signature The digital signature used to verify the authenticity and integrity of the ballot body. Generated by the server using a GS2-Key encryption key, and verified when the ballot is submitted to prevent forgery or tampering. WrittenBallot Written Ballot A data model representing a ballot with written match results. It contains user IDs and ranks, and is submitted with a signature to the Vote API. Details  ballot Ballot  Ballot gameResults List 0 ~ 10 items List of Match Results TimeSpan Time Span Represents a duration of time composed of days, hours, and minutes. Used to specify relative time offsets, such as the expiration time of a Gathering from the current time. The total duration is calculated by combining all three components. Details  days int 0 0 ~ 365 Days The number of days in the time span. Maximum 365 days. Defaults to 0. hours int 0 0 ~ 24 Hours The number of hours in the time span. Maximum 24 hours. Defaults to 0. minutes int 0 0 ~ 60 Minutes The number of minutes in the time span. Maximum 60 minutes. Defaults to 0. CurrentModelMaster Currently active Models master data This master data defines the Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Matchmaking Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data RatingModelMaster Rating Model Master Rating Model Master is data used to edit and manage Rating Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Rating Model actually referenced by the game. GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value. Details  ratingModelId string * ~ 1024 chars Rating Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SeasonModelMaster Season Model Master Season Model Master is data used to edit and manage Season Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Season Model actually referenced by the game. Season Model is master data that defines the period of persistent gatherings active for a fixed period, the maximum number of participants, and tier integration settings in Season Matchmaking. The period is managed by GS2-Schedule, and it can optionally integrate with GS2-Experience to form persistent gatherings within the same tier. Details  seasonModelId string * ~ 1024 chars Season Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management The GRN of the GS2-Experience experience model used to determine player tiers. The player’s rank within this experience model is used as their tier for matchmaking, ensuring players are grouped with others at a similar level. If not specified, tier-based grouping is disabled and all players are matched together regardless of level. challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Schedule event that defines the active period for this season. Season Gatherings can only be created and joined while this event is active. When the event period ends, the season closes and new matchmaking is no longer possible. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing matchmaking operations. enableRating bool false Enable Rating Whether to enable the Glicko-2 based rating calculation function. When enabled, players can submit match results via the Vote system and have their ratings automatically updated. Requires RatingModel master data to be configured. Defaults to false. enableDisconnectDetection string (enum) enum {   “disable”,   “enable” } “disable” Disconnect Detection Controls whether players in matchmaking must periodically report they are still waiting. When enabled, if a player does not send a keep-alive within the configured timeout period, they are automatically removed from the Gathering. This prevents “ghost” players from blocking matchmaking completion. Defaults to “disable”. Definition Description “disable” Disable “enable” Enable disconnectDetectionTimeoutSeconds int {enableDisconnectDetection} == “enable”  15 ~ 600 Disconnect Detection Timeout (seconds) The number of seconds to wait without a keep-alive report before a player is considered disconnected and removed from the Gathering. Only applies when disconnect detection is enabled. Must be between 15 and 600 seconds. * Required if enableDisconnectDetection is “enable” createGatheringTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Create Gathering Trigger Type The type of action to execute when a new Gathering is created. Can trigger GS2-Realtime room creation for real-time communication, or execute a GS2-Script for custom logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution createGatheringTriggerRealtimeNamespaceId string {createGatheringTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace to create rooms when creating a gathering * Required if createGatheringTriggerType is “gs2_realtime” createGatheringTriggerScriptId string {createGatheringTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when creating a gathering * Required if createGatheringTriggerType is “gs2_script” completeMatchmakingTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Complete Matchmaking Trigger Type The type of action to execute when matchmaking completes (all role slots are filled). Can trigger GS2-Realtime room creation for the matched players, or execute a GS2-Script for custom post-match logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution completeMatchmakingTriggerRealtimeNamespaceId string {completeMatchmakingTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to create rooms when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_realtime” completeMatchmakingTriggerScriptId string {completeMatchmakingTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_script” enableCollaborateSeasonRating string (enum) enum {   “enable”,   “disable” } “disable” Enable Season Rating Collaboration Whether to enable integration with GS2-SeasonRating for season-based rating calculations. When enabled, a rating calculation session is automatically created in the specified GS2-SeasonRating namespace when matchmaking completes. Defaults to “disable”. Definition Description “enable” Enable “disable” Disable collaborateSeasonRatingNamespaceId string {enableCollaborateSeasonRating} == “enable”  ~ 1024 chars Season Rating Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if enableCollaborateSeasonRating is “enable” collaborateSeasonRatingTtl int {enableCollaborateSeasonRating} == “enable” 60 60 ~ 7200 Season Rating Result TTL (seconds) The maximum time in seconds to wait for match result submissions via GS2-SeasonRating after matchmaking completes. If results are not submitted within this period, the rating session expires. Must be between 60 and 7200 seconds. Defaults to 60. * Required if enableCollaborateSeasonRating is “enable” changeRatingScript ScriptSetting Script setting to be executed when the rating value changes Script Trigger Reference - changeRating joinNotification NotificationSetting Join Notification Push Notification Setting for when a new player joins a Gathering. Notifies existing participants that a new player has joined, allowing the game client to update the matchmaking UI. leaveNotification NotificationSetting Leave Notification Push Notification Setting for when a player leaves a Gathering. Notifies remaining participants that a player has left, allowing the game client to reflect the change. completeNotification NotificationSetting Complete Notification Push Notification Setting for when matchmaking completes (all role slots are filled). Notifies all participants that the Gathering is full and the match can begin. changeRatingNotification NotificationSetting Change Rating Notification Push Notification Setting for when a player’s rating value changes after vote processing. Notifies the affected player of their new rating, allowing the game client to display the updated value. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, matchmaking operations (create/join/leave gathering, vote, rating changes, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing matchmaking operations. enableRating bool false Enable Rating Whether to enable the Glicko-2 based rating calculation function. When enabled, players can submit match results via the Vote system and have their ratings automatically updated. Requires RatingModel master data to be configured. Defaults to false. enableDisconnectDetection string (enum) enum {   “disable”,   “enable” } “disable” Disconnect Detection Controls whether players in matchmaking must periodically report they are still waiting. When enabled, if a player does not send a keep-alive within the configured timeout period, they are automatically removed from the Gathering. This prevents “ghost” players from blocking matchmaking completion. Defaults to “disable”. Definition Description “disable” Disable “enable” Enable disconnectDetectionTimeoutSeconds int {enableDisconnectDetection} == “enable”  15 ~ 600 Disconnect Detection Timeout (seconds) The number of seconds to wait without a keep-alive report before a player is considered disconnected and removed from the Gathering. Only applies when disconnect detection is enabled. Must be between 15 and 600 seconds. * Required if enableDisconnectDetection is “enable” createGatheringTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Create Gathering Trigger Type The type of action to execute when a new Gathering is created. Can trigger GS2-Realtime room creation for real-time communication, or execute a GS2-Script for custom logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution createGatheringTriggerRealtimeNamespaceId string {createGatheringTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace to create rooms when creating a gathering * Required if createGatheringTriggerType is “gs2_realtime” createGatheringTriggerScriptId string {createGatheringTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when creating a gathering * Required if createGatheringTriggerType is “gs2_script” completeMatchmakingTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Complete Matchmaking Trigger Type The type of action to execute when matchmaking completes (all role slots are filled). Can trigger GS2-Realtime room creation for the matched players, or execute a GS2-Script for custom post-match logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution completeMatchmakingTriggerRealtimeNamespaceId string {completeMatchmakingTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to create rooms when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_realtime” completeMatchmakingTriggerScriptId string {completeMatchmakingTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_script” enableCollaborateSeasonRating string (enum) enum {   “enable”,   “disable” } “disable” Enable Season Rating Collaboration Whether to enable integration with GS2-SeasonRating for season-based rating calculations. When enabled, a rating calculation session is automatically created in the specified GS2-SeasonRating namespace when matchmaking completes. Defaults to “disable”. Definition Description “enable” Enable “disable” Disable collaborateSeasonRatingNamespaceId string {enableCollaborateSeasonRating} == “enable”  ~ 1024 chars Season Rating Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if enableCollaborateSeasonRating is “enable” collaborateSeasonRatingTtl int {enableCollaborateSeasonRating} == “enable” 60 60 ~ 7200 Season Rating Result TTL (seconds) The maximum time in seconds to wait for match result submissions via GS2-SeasonRating after matchmaking completes. If results are not submitted within this period, the rating session expires. Must be between 60 and 7200 seconds. Defaults to 60. * Required if enableCollaborateSeasonRating is “enable” changeRatingScript ScriptSetting Script setting to be executed when the rating value changes Script Trigger Reference - changeRating joinNotification NotificationSetting Join Notification Push Notification Setting for when a new player joins a Gathering. Notifies existing participants that a new player has joined, allowing the game client to update the matchmaking UI. leaveNotification NotificationSetting Leave Notification Push Notification Setting for when a player leaves a Gathering. Notifies remaining participants that a player has left, allowing the game client to reflect the change. completeNotification NotificationSetting Complete Notification Push Notification Setting for when matchmaking completes (all role slots are filled). Notifies all participants that the Gathering is full and the match can begin. changeRatingNotification NotificationSetting Change Rating Notification Push Notification Setting for when a player’s rating value changes after vote processing. Notifies the affected player of their new rating, allowing the game client to display the updated value. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, matchmaking operations (create/join/leave gathering, vote, rating changes, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeGatherings Get a list of Gatherings Retrieves a paginated list of all gatherings in the specified namespace. This includes gatherings that are currently recruiting participants as well as those that have been completed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 acquired Result Type Description items List List of Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGathering Create a Gathering and start recruiting The recruitment criteria are the ranges of each attribute value that will be allowed to participate in the created gathering. For example, if you want to recruit players who want to participate in the same game mode, you can use the following formula to matchmaking with participation criteria players whose attribute values correspond exactly to the game mode attribute name: game mode attribute minimum: a number representing the game mode attribute maximum: a number representing the game mode to allow matchmaking between players who wish to play in the same game mode. If you wish to implement other rating-based matchmaking, you can use the By specifying a range of attribute values centered on the room creator’s rating value, you can matchmaking between players with similar rating values. You can update this recruitment criteria later, so you can gradually relax the criteria. Roles are used when you want to set the number of recruits for each role, such as 1 shield, 1 healer, 2 attackers, etc. Roles can have aliases. For example, a shield role can be further classified into two jobs : paladin and knight. In this case, the game could be implemented to advertise for recruits with the role name Shield and the alias Paladin Knight . The player then specifies their own Job as the role in their player information. In this way, both paladin and knight can participate in a gathering where the recruiting condition is shield . On the other hand, if, when creating a gathering, you only want to recruit paladins and not knights , you can specify This can be accomplished by specifying paladin directly in the name of the role to be recruited, or by not including knight in the alias. The Number of players in the Participants field specifies the number of players to be recruited. By specifying role names, you can set the number of recruits for each role name. The Participant's player info list in Participant is used when a party has been built among players in advance, or for recruiting additional players after a participant leaves. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token player Player  Own player information attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. capacityOfRoles List [] 1 ~ 5 items List of Role Capacities Defines the recruitment slots for this Gathering. Each entry specifies a role name, its aliases, and the maximum number of players that can fill that role. When all role slots reach their capacity, matchmaking is considered complete. At least 1, maximum 5 roles. allowUserIds List [] 0 ~ 100 items Allowed User IDs A whitelist of user IDs that are permitted to join this Gathering. When specified, only the listed users can participate in matchmaking for this Gathering. Useful for friend-only or invitation-based matchmaking scenarios. Maximum 100 entries. expiresAt long Gathering Expiration Time The time at which this Gathering automatically expires and is deleted. If matchmaking does not complete before this time, the Gathering is cleaned up. When not specified, the Gathering persists until matchmaking completes or it is manually deleted. expiresAtTimeSpan TimeSpan Time to expiration Result Type Description item Gathering Created Gathering Implementation Example createGatheringByUserId Create a Gathering by specifying a user ID and start recruiting The recruitment criteria are the ranges of each attribute value that will be allowed to participate in the created gathering. For example, if you want to recruit players who want to participate in the same game mode, you can use the following formula to matchmaking with participation criteria players whose attribute values correspond exactly to the game mode attribute name: game mode attribute minimum: a number representing the game mode `attribute maximum: a number representing the game mode to allow matchmaking between players who wish to play in the same game mode. If you wish to implement other rating-based matchmaking, you can use the By specifying a range of attribute values centered on the room creator’s rating value, you can matchmaking between players with similar rating values. You can update this recruitment criteria later, so you can gradually relax the criteria. Roles are used when you want to set the number of recruits for each role, such as 1 shield, 1 healer, 2 attackers, etc. Roles can have aliases. For example, a shield role can be further classified into two jobs': paladin and knight. In this case, the game could be implemented to advertise for recruits with the role name Shield and the alias Paladin Knight . The player then specifies their own Job` as the role in their player information. In this way, both paladin and knight can participate in a gathering where the recruiting condition is shield . On the other hand, if, when creating a gathering, you only want to recruit paladins and not knights , you can specify This can be accomplished by specifying paladin directly in the name of the role to be recruited, or by not including knight in the alias. The Number of players in the Participants field specifies the number of players to be recruited. By specifying role names, you can set the number of recruits for each role name. The Participant's player info list in Participant is used when a party has been built among players in advance, or for recruiting additional players after a participant leaves. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID player Player  Own player information attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. capacityOfRoles List [] 1 ~ 5 items List of Role Capacities Defines the recruitment slots for this Gathering. Each entry specifies a role name, its aliases, and the maximum number of players that can fill that role. When all role slots reach their capacity, matchmaking is considered complete. At least 1, maximum 5 roles. allowUserIds List [] 0 ~ 100 items Allowed User IDs A whitelist of user IDs that are permitted to join this Gathering. When specified, only the listed users can participate in matchmaking for this Gathering. Useful for friend-only or invitation-based matchmaking scenarios. Maximum 100 entries. expiresAt long Gathering Expiration Time The time at which this Gathering automatically expires and is deleted. If matchmaking does not complete before this time, the Gathering is cleaned up. When not specified, the Gathering persists until matchmaking completes or it is manually deleted. expiresAtTimeSpan TimeSpan Time to expiration timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Created Gathering Implementation Example updateGathering Update Gathering Updates the recruitment criteria (attribute ranges) of the specified gathering. This allows you to gradually relax or tighten the matching conditions while waiting for participants. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. accessToken string  ~ 128 chars Access token attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. Result Type Description item Gathering Gathering updated Implementation Example updateGatheringByUserId Update Gathering with User ID Updates the recruitment criteria (attribute ranges) of the specified gathering for the given user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. userId string  ~ 128 chars User ID attributeRanges List [] 0 ~ 5 items Recruitment Requirements A list of attribute range conditions that players must satisfy to join this Gathering. Each entry specifies a named attribute and its acceptable min/max range. A player’s own attribute values must fall within these ranges to participate. Maximum 5 conditions. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Gathering updated Implementation Example doMatchmakingByPlayer Find a Gathering in which the Player can participate and join. Search for a certain period of time and return a matchmaking status token' if the target is not found. Next time, the search process can be resumed from the previous time by submitting a request again with a token to keep the matchmaking status`. When all gatherings are searched but there is no gathering to join, null is returned for both the gathering and the token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). player Player  Player Information matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state Result Type Description item Gathering Participated Gathering matchmakingContextToken string Token that preserves matchmaking status Implementation Example doMatchmaking Find a Gathering you can join and participate. Search for a certain period of time and return a token holding matchmaking status if no target is found. Next time, you can resume the search process from the previous time by submitting a request again with a token to keep the matchmaking status . When all gatherings are searched but there is no gathering to join, null is returned for both the gathering and the token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token player Player  Own player information matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state Result Type Description item Gathering Participated Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example doMatchmakingByUserId Find a Gathering you can join and participate. Search for a certain period of time and return a token holding matchmaking status if no target is found. Next time, you can resume the search process from the previous time by submitting a request again with a token to keep the matchmaking status . When all gatherings are searched but there is no gathering to join, null is returned for both the gathering and the token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID player Player  Own player information matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Participated Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example ping Notify that you are waiting for matchmaking Sends a keep-alive ping to indicate the player is still actively waiting in the gathering. When disconnect detection is enabled, players who fail to ping within the configured timeout period are automatically removed from the gathering. This also checks for timed-out players and removes them. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. accessToken string  ~ 128 chars Access token Result Type Description item Gathering Gathering updated Implementation Example pingByUserId Notify that you are waiting for matchmaking by specifying user ID Sends a keep-alive ping for the specified user. Timed-out players are automatically removed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Gathering updated Implementation Example getGathering Get Gathering Retrieves the specified gathering, including its current participants, attribute ranges, capacity of roles, and expiry settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Result Type Description item Gathering Gathering Implementation Example cancelMatchmaking Cancel Matchmaking If matchmaking is completed before leaving the Gathering, a NotFoundException (404 error) will be thrown and the match will fail Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. accessToken string  ~ 128 chars Access token Result Type Description item Gathering Canceled Gathering Implementation Example cancelMatchmakingByUserId Cancel matchmaking by specifying user ID If matchmaking is completed before leaving the Gathering, a NotFoundException (404 error) will be thrown and the match will fail Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Canceled Gathering Implementation Example earlyComplete Early Complete Matchmaking Matchmaking will be completed early if the number of participants is less than the specified number. Only the player who created the Gathering can complete the match early. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. accessToken string  ~ 128 chars Access token Result Type Description item Gathering Canceled Gathering Implementation Example earlyCompleteByUserId Early Complete Matchmaking by specifying user ID Matchmaking will be completed early if the number of participants is less than the specified number. Only the player who created the Gathering can complete the match early. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Gathering Canceled Gathering Implementation Example deleteGathering Delete Gathering Completely removes the specified gathering and all associated participant data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Result Type Description item Gathering Gathering deleted Implementation Example describeSeasonGatherings Get a list of Season Gatherings Retrieves a paginated list of season gatherings for the specified season. Can optionally filter by tier to show only gatherings at a specific skill level. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long 0 ~ 9223372036854775805 Tier pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Season Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeMatchmakingSeasonGatherings Get a list of matchmaking Season Gatherings Retrieves a paginated list of season gatherings that are currently available for matchmaking. Can optionally filter by tier. Only gatherings that have not yet reached the maximum number of participants are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long 0 ~ 9223372036854775805 Tier pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Season Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example doSeasonMatchmaking Find a Season Gathering you can join and participate. Search for a certain period of time and return a token holding matchmaking status if no target is found. Next time, you can resume the search process from the previous time by submitting a request again with a token to keep the matchmaking status . When all seasonGatherings are searched but there is no seasonGathering to join, null is returned for both the seasonGathering and the token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state Result Type Description item SeasonGathering Participated Season Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example doSeasonMatchmakingByUserId Find a Season Gathering you can join and participate. Search for a certain period of time and return a token holding matchmaking status if no target is found. Next time, you can resume the search process from the previous time by submitting a request again with a token to keep the matchmaking status . When all seasonGatherings are searched but there is no seasonGathering to join, null is returned for both the seasonGathering and the token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID matchmakingContextToken string ~ 5120 chars Used to resume search Token that holds matchmaking state timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SeasonGathering Participated Season Gatherings matchmakingContextToken string Token that preserves matchmaking status Implementation Example getSeasonGathering Get Season Gathering Retrieves the specified season gathering, including its participants and tier information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonGathering SeasonGathering Implementation Example verifyIncludeParticipant Verify if persistent gathering includes user ID Verifies whether a user is or is not a participant of the specified season gathering. The verify type can be ‘include’ (assert user is a participant) or ’notInclude’ (assert user is not a participant). Returns an error if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Specified user is included in the Season Gathering “notInclude” Specified user is not included in the Season Gathering Result Type Description item SeasonGathering SeasonGathering Implementation Example verifyIncludeParticipantByUserId Verify if persistent gathering includes user ID by specifying a user ID Verifies whether the specified user is or is not a participant of the season gathering. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Specified user is included in the Season Gathering “notInclude” Specified user is not included in the Season Gathering timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SeasonGathering SeasonGathering Implementation Example deleteSeasonGathering Delete Season Gathering Deletes the specified season gathering and all associated participant records. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonGathering Season Gathering deleted Implementation Example describeJoinedSeasonGatherings Get a list of joined Season Gatherings Retrieves a paginated list of season gatherings that the requesting user has joined. Can optionally filter by season name. This allows players to see which season matchmaking groups they belong to. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token seasonName string ~ 128 chars Season Model name Season 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 acquired Result Type Description items List List of Season Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeJoinedSeasonGatheringsByUserId Get a list of joined Season Gatherings by specifying a user ID Retrieves a paginated list of season gatherings that the specified user has joined. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID seasonName string ~ 128 chars Season Model name Season 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 acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Season Gathering nextPageToken string Page token to retrieve the rest of the listing Implementation Example getJoinedSeasonGathering Get joined Season Gathering Retrieves the season gathering that the requesting user has joined for the specified season. If the target gathering no longer exists, the joined record is automatically cleaned up. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season Result Type Description item JoinedSeasonGathering JoinedSeasonGathering Implementation Example getJoinedSeasonGatheringByUserId Get joined Season Gathering by specifying the user ID Retrieves the season gathering that the specified user has joined for the given season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item JoinedSeasonGathering JoinedSeasonGathering Implementation Example describeRatings Get a list of ratings Retrieves a paginated list of all rating entries for the requesting user. Each rating entry contains the current rating value and rating deviation (RD) based on the Glicko-2 algorithm. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Rating nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeRatingsByUserId Get a list of ratings by specifying a user ID Retrieves a paginated list of all rating entries for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Rating nextPageToken string Page token to retrieve the rest of the listing Implementation Example getRating Get Rating Retrieves the current rating value and rating deviation (RD) for the specified rating model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token ratingName string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Rating Rating Implementation Example getRatingByUserId Get Rating by specifying a user ID Retrieves the current rating value and rating deviation (RD) for the specified user and rating model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID ratingName string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Rating Rating Implementation Example putResult Recalculate rating values The rating calculation process uses a calculation algorithm based on the Glicko-2 rating system. The initial rating value is 1500, and the more a player wins against a distant opponent, the greater the increase in rating value, and the greater the decrease in rating value for the losing side. The rating calculation requires list of participating user IDs. Therefore, it is not appropriate to call this API directly from the client. It should be called from the game server, which can determine whether the game has been won or lost. If a client-driven game, such as a P2P game, is being realized, please use the voting function to determine the winner. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gameResults List 0 ~ 10 items List of Results Result Type Description items List List of Updated Rating Implementation Example deleteRating Delete Rating Deletes the specified user’s rating record, resetting their rating to the initial value on next calculation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID ratingName string  ~ 128 chars Rating name Rating-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Rating Rating deleted Implementation Example getBallot Prepared ballot along with signatures Generates a cryptographically signed ballot for the requesting user to use in the voting process. The ballot contains the rating name, gathering name, user ID, and number of participants, and is signed using the specified GS2-Key for tamper detection. The returned body and signature should be submitted to the Vote or VoteMultiple endpoint. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. accessToken string  ~ 128 chars Access token numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot body string Data to be signed signature string Signature Implementation Example getBallotByUserId Create ballot with signatures, specifying user ID Generates a cryptographically signed ballot for the specified user to use in the voting process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. userId string  ~ 128 chars User ID numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Ballot Ballot body string Data to be signed signature string Signature Implementation Example vote Vote on match results Voting must take place within 5 minutes of the first vote being cast. This means that the results will not be reflected immediately, but approximately 5 minutes after the start of voting or when all players have cast their votes. If all ballots are not collected within 5 minutes, the result will be determined by a majority vote based on the votes cast at that time. If the number of votes for each result is the same, the result will be discarded (the behavior can be changed by script). If you want to reflect the result immediately, the representative player of the winning side can collect ballots from each player and call voteMultiple to reflect the result immediately. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ballotBody string  ~ 1024 chars Data for ballot signature targets ballotSignature string  ~ 256 chars Signature gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot Implementation Example voteMultiple Compile match results and vote The side that wins the game collects the ballots of other players and uses them to vote collectively. We say ’the winning side’ because there is an incentive for the losing side to report that they won, but not vice versa. It is possible that the losing side will not hand in their ballots, but even in that case, if there is a majority of ballots, the results can still be passed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). signedBallots List 0 ~ 10 items List of Ballot with signatures gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot Implementation Example commitVote Forced determination of voting status Forces the completion of the voting process for the specified gathering. The result is determined by majority vote based on the ballots collected so far. If votes are tied, the result is discarded (behavior can be changed by script). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). gatheringName string  UUID ~ 128 chars Gathering name Maintains a unique name for each Gathering. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each Gathering. Result Type Description Implementation Example describeRatingModels Get a list of Rating Models Retrieves the list of currently active rating models for the specified namespace. Rating models define the Glicko-2 algorithm parameters such as initial value and volatility. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Rating Model Implementation Example getRatingModel Get Rating Model Retrieves the specified rating model, including its initial value and volatility settings for the Glicko-2 algorithm. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RatingModel Rating Model Implementation Example describeSeasonModels Get a list of Season Models Retrieves the list of currently active season models for the specified namespace. Season models define the maximum number of participants, tier calculation using an experience model, and challenge period events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Season Model Implementation Example getSeasonModel Get Season Model Retrieves the specified season model, including its maximum participants, experience model ID for tier calculation, and challenge period event ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModel Season Model Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently active rating and season model masters in a format suitable for activation. The exported data can be used to update master data in another namespace or stored as a backup. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Models master data that can be activated Implementation Example getCurrentModelMaster Get currently active model master data Retrieves the currently active rating and season model master data for the specified namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Currently active Models master data Implementation Example preUpdateCurrentModelMaster Update currently active Models master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentModelMaster Update currently active Models master data Updates the currently active model master data. Supports two modes: ‘direct’ for inline settings, and ‘preUpload’ for applying settings previously uploaded via the 3-phase update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentModelMaster Updated master data of the currently active Models Implementation Example updateCurrentModelMasterFromGitHub Update currently active Models master data from GitHub Updates the currently active model master data by fetching it from a specified GitHub repository. The API key stored in GS2-Key is used for authentication, and you can specify the branch, tag, or commit hash to checkout. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentModelMaster Updated master data of the currently active Models Implementation Example describeRatingModelMasters Get a list of Rating Model Masters Retrieves a paginated list of rating model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Rating Model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Rating Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRatingModelMaster Create a new Rating Model Master Creates a new rating model master with the specified Glicko-2 algorithm parameters. You can configure the initial rating value (default: 1500) and volatility for rating calculations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. Result Type Description item RatingModelMaster Created Rating Model Master Implementation Example getRatingModelMaster Get Rating Model Master Retrieves the specified rating model master, including its initial value and volatility settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RatingModelMaster Rating Model Master Implementation Example updateRatingModelMaster Update Rating Model Master Updates the specified rating model master. You can modify the description, metadata, initial value, and volatility settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. Result Type Description item RatingModelMaster Rating Model Master updated Implementation Example deleteRatingModelMaster Delete Rating Model Master Deletes the specified rating model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ratingName string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RatingModelMaster Rating Model Master deleted Implementation Example describeSeasonModelMasters Get a list of Season Model Masters Retrieves a paginated list of season model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Season Model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Season Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSeasonModelMaster Create a new Season Model Master Creates a new season model master with the specified configuration. You can configure the maximum number of participants per gathering, an experience model for tier-based matchmaking, and a challenge period event to control when matchmaking is available. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item SeasonModelMaster Season Model Master created Implementation Example getSeasonModelMaster Get Season Model Master Retrieves the specified season model master, including its maximum participants, experience model ID, and challenge period event ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModelMaster Season Model Master Implementation Example updateSeasonModelMaster Update Season Model Master Updates the specified season model master. You can modify the description, metadata, maximum participants, experience model ID, and challenge period event ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item SeasonModelMaster Season Model Master updated Implementation Example deleteSeasonModelMaster Delete Season Model Master Deletes the specified season model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModelMaster Season Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Matchmaking SDK for various programming languages\n","title":"GS2-Matchmaking SDK API Reference","url":"/api_reference/matchmaking/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Layer Layer Details  layerId string * ~ 1024 chars Layer A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name numberOfMinEntries int 5 1 ~ 1000 Attempts to join with other nodes when the number of entities in a node falls below a specified value numberOfMaxEntries int 20 1 ~ 1000 Attempts to split a node if the number of entities in the node exceeds the specified value createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server Spatial Spatial Details  spatialId string * ~ 1024 chars Serial Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position Position  Position vector Vector  Vector r float 1 0 ~ 10000 Radius lastSyncAt long Last Synchronization Date and Time for Layer createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server AreaModel Area divides space, and different areas can be treated as different spaces even if they have the same coordinates. Details  areaModelId string * ~ 1024 chars Area Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Area Model name 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. layerModels List [] 0 ~ 1000 items List of layer models LayerModel Layers allow for multiple logical hierarchies within a single space. For example, it solves the problem of an Enemy being invisible in a space with a large number of characters. Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance. Details  layerModelId string * ~ 1024 chars Layer Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Layer Model name 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. Position Position Details  x float  -1048574 ~ 1048574 X position y float  -1048574 ~ 1048574 Y position z float  -1048574 ~ 1048574 Z position MyPosition My Location Details  position Position  Position vector Vector  Vector r float 1 0 ~ 10000 Radius Scope Surroundings to be acquired Details  layerName string  ~ 128 chars Layer Model name r float  1 ~ 16777214 Radius limit int  1 ~ 100 Maximum number of result Vector Position Details  x float  -1048574 ~ 1048574 X position y float  -1048574 ~ 1048574 Y position z float  -1048574 ~ 1048574 Z position CurrentFieldMaster Currently active Field Model master data This master data defines the Field Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-MegaField Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data AreaModelMaster Area divides space, and different areas can be treated as different spaces even if they have the same coordinates. Details  areaModelMasterId string * ~ 1024 chars Area Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Area Model name description string ~ 1024 chars Description 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LayerModelMaster Layers allow for multiple logical hierarchies within a single space. For example, it solves the problem of an Enemy being invisible in a space with a large number of characters. Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance. Details  layerModelMasterId string * ~ 1024 chars Layer Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Layer Model name description string ~ 1024 chars Description 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example putPosition Put position Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position Position  Position vector Vector  Vector r float 1 0 ~ 10000 Radius Result Type Description item Spatial Spatial Implementation Example putPositionByUserId Put position by specifying a user ID Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position Position  Position vector Vector  Vector r float 1 0 ~ 10000 Radius timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Spatial Spatial Implementation Example fetchPosition Fetch position Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name userIds List  1 ~ 100 items List of User IDs Result Type Description items List List of Spatial Implementation Example fetchPositionFromSystem Fetch position Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name userIds List  1 ~ 100 items List of User IDs Result Type Description items List List of Spatial Implementation Example nearUserIds Fetch list of nearby user IDs Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name point Position  Point r float  1 ~ 16777214 Radius limit int  1 ~ 100 Maximum number of result Result Type Description items List List of nearby user IDs Implementation Example nearUserIdsFromSystem Fetch list of nearby user IDs Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name point Position  Point r float  1 ~ 16777214 Radius limit int  1 ~ 100 Maximum number of result Result Type Description items List List of nearby user IDs Implementation Example action Put position Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position MyPosition  My Location scopes List 0 ~ 10 items List of Scope of acquisition by other players Result Type Description items List List of Spatial Implementation Example actionByUserId Put position by specifying a user ID Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID areaModelName string  ~ 128 chars Area name layerModelName string  ~ 128 chars Layer name position MyPosition  My Location scopes List 0 ~ 10 items List of Scope of acquisition by other players timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Spatial Implementation Example describeAreaModels Get a list of Area Models Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Area Models Implementation Example getAreaModel Get Area Model Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description item AreaModel Area Model Implementation Example describeLayerModels Get a list of Layer Models Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description items List List of Layer Models Implementation Example getLayerModel Get Layer Model Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name layerModelName string  ~ 128 chars Layer Model name Result Type Description item LayerModel Implementation Example exportMaster Export Model Master in a master data format that can be activated Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentFieldMaster master data that can be activated Implementation Example getCurrentFieldMaster Get currently active Field Model master data Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentFieldMaster Currently active Field Model master data Implementation Example preUpdateCurrentFieldMaster Update currently active Field Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentFieldMaster Update currently active Field Model master data Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentFieldMaster Updated master data of the currently active Field Models Implementation Example updateCurrentFieldMasterFromGitHub Update currently active Field Model master data from GitHub Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentFieldMaster Updated master data of the currently active Field Models Implementation Example describeAreaModelMasters Get a list of Area Model Masters Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 acquired Result Type Description items List List of Area Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createAreaModelMaster Create a new Area Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Area Model name description string ~ 1024 chars Description 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. Result Type Description item AreaModelMaster Area Model Master created Implementation Example getAreaModelMaster Get Area Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description item AreaModelMaster Area Model Master Implementation Example updateAreaModelMaster Update Area Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name description string ~ 1024 chars Description 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. Result Type Description item AreaModelMaster Area Model Master updated Implementation Example deleteAreaModelMaster Delete Area Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name Result Type Description item AreaModelMaster Area Model Master deleted Implementation Example describeLayerModelMasters Get a list of Layer Model Masters Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Layer Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createLayerModelMaster Create a new Layer Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name name string  ~ 128 chars Layer Model name description string ~ 1024 chars Description 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. Result Type Description item LayerModelMaster Item Model Master created Implementation Example getLayerModelMaster Get Layer Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name layerModelName string  ~ 128 chars Layer Model name Result Type Description item LayerModelMaster Layer Model Master Implementation Example updateLayerModelMaster Update Layer Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name layerModelName string  ~ 128 chars Layer Model name description string ~ 1024 chars Description 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. Result Type Description item LayerModelMaster Layer Model Master updated Implementation Example deleteLayerModelMaster Delete Layer Model Master Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). areaModelName string  ~ 128 chars Area Model name layerModelName string  ~ 128 chars Layer Model name Result Type Description item LayerModelMaster Layer Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-MegaField SDK for various programming languages\n","title":"GS2-MegaField SDK API Reference","url":"/api_reference/mega_field/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used when granting mission completion rewards. missionCompleteScript ScriptSetting Script to run when a mission is accomplished Script Trigger Reference - missionComplete counterIncrementScript ScriptSetting Script to run when the counter rises Script Trigger Reference - counterIncrement receiveRewardsScript ScriptSetting Script to run when a reward is received Script Trigger Reference - receiveRewards completeNotification NotificationSetting  Push notifications when mission tasks are accomplished Configures push notifications delivered via GS2-Gateway when a mission task’s completion conditions are met. This allows the game client to immediately reflect the accomplishment in the UI. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for debugging counter increments, mission completions, and reward receipts. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Complete Mission Completion Status Tracks a user’s mission completion and reward receipt status for a specific mission group. Maintains separate lists for accomplished task names and reward-received task names, distinguishing between tasks that have been completed and those whose rewards have actually been claimed. Details  completeId string * ~ 1024 chars Completion Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. completedMissionTaskNames List [] 0 ~ 1000 items List of Completed Task Names The names of mission tasks that the user has accomplished (completion conditions met). A task appears in this list when its counter reaches the target value or verify actions pass, regardless of whether the reward has been claimed. receivedMissionTaskNames List [] 0 ~ 1000 items List of Reward received Task Names The names of mission tasks for which the user has already claimed the completion reward. A task must be in the completed list before its reward can be received. nextResetAt long Next reset timing The timestamp at which this mission group’s completion status will be reset. Determined by the mission group’s reset type and timing settings. Null if the reset type is “notReset”. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Counter Counter A counter is an entity that keeps track of mission progress for each game player. Counter values are aggregated by the duration of the associated task. Therefore, one counter can have multiple values. For example, for a quest clear count counter, the number of times the quest was completed this month, this week, and today. For example, a quest clear count counter could have the following values. Details  counterId string * ~ 1024 chars Counter A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID name string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. values List [] 0 ~ 32 items Values The list of scoped values for this counter. Each entry holds the counter value for a specific scope (reset timing or verify action condition), along with the next reset time. A single counter holds multiple values for different scopes simultaneously. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision CounterScopeModel Counter Reset Timing Model Defines a scope for a counter, which determines how and when the counter value is reset. A scope can be either a reset timing (daily, weekly, monthly, fixed-day interval, or never) or a verify action condition. Each counter can have multiple scopes to track values across different periods. Details  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Determines how the counter scope is defined. “resetTiming” uses a periodic reset schedule, while “verifyAction” uses a verify action to determine whether the counter value applies. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the counter value for this scope is reset. Choose from: not reset (permanent cumulative), daily, weekly, monthly, or every fixed number of days. Only used when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the counter value resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the counter value resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the counter value resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name A unique name that identifies this verify action condition scope. Used to look up the corresponding scoped value in the counter. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” condition VerifyAction {scopeType} == “verifyAction”  Condition The verify action that determines whether the counter value for this scope is applicable. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between counter value resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” CounterModel Counter Model Counter Model is an entity that can be set as a condition for accomplishing mission tasks. Since counter values can be referenced by multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions. Details  counterId string * ~ 1024 chars Counter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Specifies the GS2-Schedule event that defines the time window during which this counter can be incremented or decremented. If not set, the counter can be operated at any time. MissionGroupModel Mission Group Model A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission. Details  missionGroupId string * ~ 1024 chars Mission Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. tasks List [] 0 ~ 1000 items List of Mission Task The mission tasks belonging to this group. Each task defines a completion condition (counter threshold or verify actions) and the rewards granted upon accomplishment. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” MissionTaskModel Mission Task Model A mission task is an entity that defines the conditions under which a reward will be given if the value of the associated counter exceeds a certain level. Details  missionTaskId string * ~ 1024 chars Mission Task A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” [] 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received Specifies the GS2-Schedule event that defines the time window during which the mission task rewards can be claimed. If not set, rewards can be received at any time after accomplishment. premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. TargetCounterModel Target Counter Information about the counter that serves as the achievement goal for the mission Details  counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Specifies which type of counter scope to use for the mission completion check. “resetTiming” evaluates the counter value for a specific reset period, while “verifyAction” evaluates the value for a named condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming” Target Reset timing Specifies which reset timing scope of the counter to check against the target value. For example, selecting “daily” means the task checks the daily counter value. If omitted, the mission group’s reset timing is used. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Enabled only if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition scope to check against the target value. Must match a conditionName defined in the counter model’s scopes. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long  0 ~ 9223372036854775805 Target value The threshold value that the counter’s scoped value must reach or exceed for the mission task to be considered accomplished. ScopedValue Scoped Value Represents a counter value within a specific scope. Each scoped value holds the accumulated count for a particular reset timing (e.g., daily, weekly, monthly) or verify action condition. When the reset timing arrives, the value is reset to zero. The counter value has an upper bound and will not exceed the maximum value even when incremented. Details  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Indicates whether this scoped value is based on a reset timing schedule or a verify action condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming”  Reset timing The reset timing for this scoped value. Determines the period over which the counter value is accumulated before being reset. Only applicable when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Required if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition that this scoped value corresponds to. Used to identify which condition scope this value belongs to. Only applicable when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long 0 0 ~ 9223372036854775805 Count value The accumulated counter value for this scope. Increases when the counter is incremented and decreases when decremented. The value is capped at the maximum and will not go below zero. nextResetAt long Next reset timing The timestamp at which this scoped value will be reset to zero. Calculated based on the reset type and timing settings. Null if the reset type is “notReset” or if the scope type is “verifyAction”. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentMissionMaster Currently active Mission Model master data This master data defines the Mission Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Mission Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data CounterModelMaster Counter Model Master Counter model Master is data used to edit and manage Counter Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Counter Model actually referenced by the game. Counter Model is an entity that can be set as a condition for accomplishment of mission tasks. Since counter values can be referenced from multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions. Details  counterId string * ~ 1024 chars Counter Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Specifies the GS2-Schedule event that defines the time window during which this counter can be incremented or decremented. If not set, the counter can be operated at any time. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision MissionGroupModelMaster Mission Group Model Master Mission Group Model Master is data used to edit and manage Mission Group Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Mission Group Model actually referenced by the game. A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission. Details  missionGroupId string * ~ 1024 chars Mission Group Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision MissionTaskModelMaster Mission Task Model Master Mission Task Model Master is data used to edit and manage Mission Task Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Mission Task Model actually referenced by the game. A mission task is an entity that defines the conditions under which a reward will be given if the value of the associated counter exceeds a certain level. Details  missionTaskId string * ~ 1024 chars Mission Task Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received Specifies the GS2-Schedule event that defines the time window during which the mission task rewards can be claimed. If not set, rewards can be received at any time after accomplishment. premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used when granting mission completion rewards. missionCompleteScript ScriptSetting Script to run when a mission is accomplished Script Trigger Reference - missionComplete counterIncrementScript ScriptSetting Script to run when the counter rises Script Trigger Reference - counterIncrement receiveRewardsScript ScriptSetting Script to run when a reward is received Script Trigger Reference - receiveRewards completeNotification NotificationSetting  Push notifications when mission tasks are accomplished Configures push notifications delivered via GS2-Gateway when a mission task’s completion conditions are met. This allows the game client to immediately reflect the accomplishment in the UI. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for debugging counter increments, mission completions, and reward receipts. Result Type Description item Namespace Created namespace Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used when granting mission completion rewards. missionCompleteScript ScriptSetting Script to run when a mission is accomplished Script Trigger Reference - missionComplete counterIncrementScript ScriptSetting Script to run when the counter rises Script Trigger Reference - counterIncrement receiveRewardsScript ScriptSetting Script to run when a reward is received Script Trigger Reference - receiveRewards completeNotification NotificationSetting  Push notifications when mission tasks are accomplished Configures push notifications delivered via GS2-Gateway when a mission task’s completion conditions are met. This allows the game client to immediately reflect the accomplishment in the UI. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for debugging counter increments, mission completions, and reward receipts. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeCompletes Get a list of Completion Statuses Retrieves a paginated list of mission completion statuses for the requesting user. Each completion status tracks which mission tasks within a mission group have been completed and which rewards have been received. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Completion Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeCompletesByUserId Get a list of Completion Statuses by specifying a user ID Retrieves a paginated list of mission completion statuses for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Completion Statuses nextPageToken string Page token to retrieve the rest of the listing Implementation Example complete Issue transactions to receive rewards for mission accomplishment Verifies that the specified mission task is completed and issues a transaction containing the configured reward acquire actions. The task must be in a completed state (counter conditions met) and not yet received. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name Task-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example completeByUserId Issue transactions to receive rewards for mission accomplishment by specifying a user ID Verifies that the specified mission task is completed and issues a transaction containing the configured reward acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name Task-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example batchComplete Issue transactions to receive rewards for multiple mission tasks in bulk Processes multiple mission task completions at once within the same mission group, issuing a combined transaction for all rewards. Each task must be in a completed state and not yet received. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. accessToken string  ~ 128 chars Access token missionTaskNames List  1 ~ 100 items Task name list config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example batchCompleteByUserId Issue transactions to receive rewards for multiple mission tasks in bulk by specifying a user ID Processes multiple mission task completions at once within the same mission group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID missionTaskNames List  1 ~ 100 items Task name list config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet to receive rewards for mission accomplishment stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example receiveByUserId Receive rewards for mission accomplishment Marks the specified mission task as received for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Received Completion Status Implementation Example batchReceiveByUserId Receive rewards for multiple mission tasks in bulk Marks multiple mission tasks as received at once within the same mission group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID missionTaskNames List  1 ~ 100 items Task name list timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Received Completion Status Implementation Example revertReceiveByUserId Revert the status of mission accomplishment to unreceived Reverts the received status of a mission task back to unreceived. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Received Completion Status Implementation Example getComplete Get Completion Statuses Retrieves the completion status for the specified mission group for the requesting user. The status includes lists of completed mission tasks and received mission tasks. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. accessToken string  ~ 128 chars Access token Result Type Description item Complete Completion Statuses Implementation Example getCompleteByUserId Get Completion Status by specifying a user ID Retrieves the completion status for the specified mission group for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Completion Statuses Implementation Example evaluateComplete Re-evaluate Completion Status Re-evaluates all counter values against mission task conditions within the specified mission group. Use this when mission tasks are added or modified after counters have already been incremented, to determine newly completed tasks. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. Result Type Description item Complete Completion Status updated Implementation Example evaluateCompleteByUserId Re-evaluate Completion Status by specifying a user ID Re-evaluates all counter values against mission task conditions within the specified mission group. Use this when mission tasks are added or modified after counters have already been incremented. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Completion Status updated Implementation Example deleteCompleteByUserId Delete Completion Status Deletes all completion status records for the specified mission group and user. This removes both completed and received status, effectively resetting the user’s progress for the mission group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Completion Status deleted Implementation Example verifyComplete Verify Completion Status Verifies the completion or receipt status of a mission task. Supported verification types: ‘completed’ (task is completed), ’notCompleted’ (task is not completed), ‘received’ (reward received), ’notReceived’ (reward not received), ‘completedAndNotReceived’ (completed but reward not yet received). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. accessToken string  ~ 128 chars Access token verifyType string (enum) enum {   “completed”,   “notCompleted”,   “received”,   “notReceived”,   “completedAndNotReceived” }  Type of verification Definition Description “completed” Condition is achieved “notCompleted” Condition is not achieved “received” Reward has been received “notReceived” Reward has not been received “completedAndNotReceived” Condition is achieved and reward has not been received missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Complete Completion Status deleted Implementation Example verifyCompleteByUserId Verify Completion Status by specifying a user ID Verifies the completion or receipt status of a mission task for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID verifyType string (enum) enum {   “completed”,   “notCompleted”,   “received”,   “notReceived”,   “completedAndNotReceived” }  Type of verification Definition Description “completed” Condition is achieved “notCompleted” Condition is not achieved “received” Reward has been received “notReceived” Reward has not been received “completedAndNotReceived” Condition is achieved and reward has not been received missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Complete Completion Status deleted Implementation Example describeCounters Get a list of counters Retrieves a paginated list of counters for the requesting user. Each counter contains scoped values that track progress toward mission task conditions, with values separated by reset period (daily, weekly, monthly, etc.). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeCountersByUserId Get a list of counters by specifying a user ID Retrieves a paginated list of counters for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Counter nextPageToken string Page token to retrieve the rest of the listing Implementation Example increaseCounterByUserId Increase counter by specifying a user ID Adds the specified value to the counter for the specified user. After incrementing, all mission tasks referencing this counter are automatically re-evaluated, and any newly completed missions are returned in the changedCompletes response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID value long  1 ~ 9223372036854775805 Value to be added timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counters increased changedCompletes List List of updated Completion Statuses Implementation Example setCounterByUserId Set counter by specifying a user ID Sets the counter scoped values directly for the specified user, replacing existing values. Returns both the old and new counter states, as well as any newly completed missions in the changedCompletes response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID values List 0 ~ 20 items List of values to be set timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counters increased old Counter Counter after counter addition changedCompletes List List of updated Completion Statuses Implementation Example decreaseCounter Decrease counter Subtracts the specified value from the counter for the requesting user. After decrementing, all mission tasks referencing this counter are automatically re-evaluated, and any missions whose completion status changed are returned in the changedCompletes response. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. accessToken string  ~ 128 chars Access token value long  1 ~ 9223372036854775805 Value to be subtracted Result Type Description item Counter Counters decreased changedCompletes List List of updated Completion Statuses Implementation Example decreaseCounterByUserId Decrease counter by specifying a user ID Subtracts the specified value from the counter for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID value long  1 ~ 9223372036854775805 Value to be subtracted timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counters decreased changedCompletes List List of updated Completion Statuses Implementation Example getCounter Get Counter Retrieves the specified counter for the requesting user, including all scoped values (per reset period). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. accessToken string  ~ 128 chars Access token Result Type Description item Counter Counter Implementation Example getCounterByUserId Get counter by specifying a user ID Retrieves the specified counter for the specified user, including all scoped values. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter Implementation Example verifyCounterValue Verify counter value Verifies that a counter’s scoped value meets the specified condition. Supported verification types: ’less’, ’lessEqual’, ‘greater’, ‘greaterEqual’, ’equal’, ’notEqual’. The verification targets a specific scope (reset type and condition) of the counter. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Counter value is less than the specified value “lessEqual” Counter value is less than or equal to the specified value “greater” Counter value is greater than the specified value “greaterEqual” Counter value is greater than or equal to the specified value “equal” Counter value is equal to the specified value “notEqual” Counter value is not equal to the specified value scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Indicates whether this scoped value is based on a reset timing schedule or a verify action condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming”  Reset timing The reset timing for this scoped value. Determines the period over which the counter value is accumulated before being reset. Only applicable when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Required if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition that this scoped value corresponds to. Used to identify which condition scope this value belongs to. Only applicable when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long 0 0 ~ 9223372036854775805 Count value The accumulated counter value for this scope. Increases when the counter is incremented and decreases when decremented. The value is capped at the maximum and will not go below zero. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Result Type Description item Counter Counter Implementation Example verifyCounterValueByUserId Verify counter value by specifying a user ID Verifies that a counter’s scoped value meets the specified condition for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Counter value is less than the specified value “lessEqual” Counter value is less than or equal to the specified value “greater” Counter value is greater than the specified value “greaterEqual” Counter value is greater than or equal to the specified value “equal” Counter value is equal to the specified value “notEqual” Counter value is not equal to the specified value scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Indicates whether this scoped value is based on a reset timing schedule or a verify action condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming”  Reset timing The reset timing for this scoped value. Determines the period over which the counter value is accumulated before being reset. Only applicable when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Required if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition that this scoped value corresponds to. Used to identify which condition scope this value belongs to. Only applicable when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long 0 0 ~ 9223372036854775805 Count value The accumulated counter value for this scope. Increases when the counter is incremented and decreases when decremented. The value is capped at the maximum and will not go below zero. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter Implementation Example resetCounter Reset counter Resets the counter values for the specified scopes. Only the scoped values matching the specified scope types are reset; other scoped values remain unchanged. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. scopes List  1 ~ 20 items List of scopes Result Type Description item Counter Counter deleted Implementation Example resetCounterByUserId Reset counter by specifying a user ID Resets the counter values for the specified scopes for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. scopes List  1 ~ 20 items List of scopes timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter deleted Implementation Example deleteCounter Delete counters Deletes the specified counter and all its scoped values for the requesting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. Result Type Description item Counter Counter deleted Implementation Example deleteCounterByUserId Delete counters by specifying a user ID Deletes the specified counter and all its scoped values for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Counter Counter deleted Implementation Example describeCounterModels Get a list of Counter Models Retrieves the list of currently active counter models for the specified namespace. Counter models define the scopes (reset timing such as daily, weekly, monthly) and conditions under which counters operate. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Counter Model Implementation Example getCounterModel Get Counter Model Retrieves the specified counter model, including its scopes, reset conditions, and challenge period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CounterModel Counter Model Implementation Example describeMissionGroupModels Get a list of Mission Group Models Retrieves the list of currently active mission group models for the specified namespace. Mission group models define groups of mission tasks with a common reset type (daily, weekly, monthly, or none). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Mission Group Model Implementation Example getMissionGroupModel Get Mission Group Model Retrieves the specified mission group model, including its reset type, reset timing settings, and the list of mission tasks it contains. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionGroupModel Mission Group Model Implementation Example describeMissionTaskModels Get a list of Mission Task Models Retrieves the list of currently active mission task models within the specified mission group. Mission task models define individual tasks with target counter conditions, completion verification types, and reward actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Mission Task Model Implementation Example getMissionTaskModel Get Mission Task Model Retrieves the specified mission task model, including its target counter, completion verification type, reward acquire actions, and prerequisite mission task configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionTaskModel Mission Task Model Implementation Example exportMaster Export Mission Model Master in a master data format that can be activated Exports the currently active mission group models, mission task models, and counter models in a format suitable for activation. The exported data can be used to update master data in another namespace or stored as a backup. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentMissionMaster Mission Model Master data that can be activated Implementation Example getCurrentMissionMaster Get currently active Mission Model master data Retrieves the currently active mission model master data for the specified namespace, including mission group models, mission task models, and counter models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentMissionMaster Currently active Mission Model master data Implementation Example preUpdateCurrentMissionMaster Update currently active Mission Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentMissionMaster Update currently active Mission Model master data Updates the currently active mission model master data. Supports two modes: ‘direct’ for inline settings, and ‘preUpload’ for applying settings previously uploaded via the 3-phase update process. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentMissionMaster Updated master data of the currently active Mission Models Implementation Example updateCurrentMissionMasterFromGitHub Update currently active Mission Model master data from GitHub Updates the currently active mission model master data by fetching it from a specified GitHub repository. The API key stored in GS2-Key is used for authentication, and you can specify the branch, tag, or commit hash to checkout. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentMissionMaster Updated master data of the currently active Mission Models Implementation Example describeCounterModelMasters Get a list of Counter Model Masters Retrieves a paginated list of counter model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Counter Model name prefix 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 List of Counter Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createCounterModelMaster Create a new Counter Model Master Creates a new counter model master with the specified configuration. You can configure scopes that define reset conditions (daily, weekly, monthly, or custom) and a challenge period event to control when the counter is active. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Result Type Description item CounterModelMaster Counter Model Master created Implementation Example getCounterModelMaster Get Counter Model Master Retrieves the specified counter model master, including its scopes, reset conditions, and challenge period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CounterModelMaster Counter Model Master Implementation Example updateCounterModelMaster Update Counter Model Master Updates the specified counter model master. You can modify the metadata, description, scopes, and challenge period event ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Result Type Description item CounterModelMaster Counter Model Master updated Implementation Example deleteCounterModelMaster Delete Counter Model Master Deletes the specified counter model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CounterModelMaster Counter Model Master deleted Implementation Example describeMissionGroupModelMasters Get a list of Mission Group Model Masters Retrieves a paginated list of mission group model masters for the specified namespace. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by mission group name prefix 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 List of Mission Group Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createMissionGroupModelMaster Create a new Mission Group Model Master Creates a new mission group model master with the specified configuration. You can configure the reset type (daily, weekly, monthly, or none), reset timing (hour, day of week/month, anchor timestamp), and a notification namespace for completion events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. Result Type Description item MissionGroupModelMaster Mission Group Model Master created Implementation Example getMissionGroupModelMaster Get Mission Group Model Master Retrieves the specified mission group model master, including its reset type, reset timing, and notification setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionGroupModelMaster Mission Group Model Master Implementation Example updateMissionGroupModelMaster Update Mission Group Model Master Updates the specified mission group model master. You can modify the metadata, description, reset type, reset timing, and notification setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. Result Type Description item MissionGroupModelMaster Mission Group Model Master updated Implementation Example deleteMissionGroupModelMaster Delete Mission Group Model Master Deletes the specified mission group model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionGroupModelMaster Mission Group Model Master deleted Implementation Example describeMissionTaskModelMasters Get a list of Mission Task Model Masters Retrieves a paginated list of mission task model masters within the specified mission group. Can optionally filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Mission Task Model Master name prefix missionGroupName string  ~ 128 chars Mission Group Model name Mission Group 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 List of Mission Task Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createMissionTaskModelMaster Create a new Mission Task Model Master Creates a new mission task model master with the specified configuration. You can configure the target counter and threshold, completion verification type (counter value or custom consume actions), reward acquire actions, a challenge period event, and a prerequisite mission task. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. Result Type Description item MissionTaskModelMaster Mission Task Model Master created Implementation Example getMissionTaskModelMaster Get Mission Task Model Master Retrieves the specified mission task model master, including its target counter, completion verification type, reward actions, and prerequisite configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionTaskModelMaster Mission Task Model Master Implementation Example updateMissionTaskModelMaster Update Mission Task Model Master Updates the specified mission task model master. You can modify the metadata, description, target counter, completion verification type, reward actions, challenge period event, and prerequisite mission task. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. description string ~ 1024 chars Description verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. Result Type Description item MissionTaskModelMaster Mission Task Model Master updated Implementation Example deleteMissionTaskModelMaster Delete Mission Task Model Master Deletes the specified mission task model master. This does not affect the currently active master data until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MissionTaskModelMaster Mission Task Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Mission SDK for various programming languages\n","title":"GS2-Mission SDK API Reference","url":"/api_reference/mission/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing money operations. priority string (enum) enum {   “free”,   “paid” }  Consumption Priority Determines the order in which paid and free currency is consumed when withdrawing from the wallet. When set to “free”, free currency (price=0) is consumed first, then paid currency from the highest unit price. When set to “paid”, paid currency is consumed first starting from the highest unit price, then free currency. Definition Description “free” Prioritize the use of free currency “paid” Prioritize the use of paid currency shareFree bool  Share Free Currency Whether free currency is shared across all wallet slots. When enabled, free currency balances are synchronized from slot 0 to all other slots, allowing players on different platforms to share the same free currency pool. Paid currency always remains separate per slot regardless of this setting. currency string (enum) enum {   “JPY”,   “USD”,   “TWD” }  Currency Type The real-world currency used for pricing and Funds Settlement Act compliance calculations. This determines the unit of measurement for tracking paid currency values and calculating refund obligations. Cannot be changed after namespace creation. Definition Description “JPY” JPY “USD” USD “TWD” TWD appleKey string ~ 1024 chars Apple AppStore Bundle ID The Bundle ID of your iOS app, used to verify Apple AppStore purchase receipts. Required when accepting in-app purchases from iOS devices. googleKey string ~ 5120 chars Google PlayStore Private Key The service account private key for Google Play, used to verify Google Play purchase receipts. Required when accepting in-app purchases from Android devices. enableFakeReceipt bool false Enable Fake Receipt Whether to accept fake purchase receipts generated by Unity Editor for testing purposes. Should only be enabled in development/test environments and must be disabled in production to prevent unauthorized currency grants. Defaults to false. createWalletScript ScriptSetting Create Wallet Script Script to run when a new wallet is created for the first time. Wallets are auto-created on first access, so this script triggers when a player first interacts with the currency system. depositScript ScriptSetting Deposit Script Script to run when currency is added to the wallet. Triggered for both paid currency deposits (from store purchases) and free currency grants. withdrawScript ScriptSetting Withdraw Script Script to run when currency is consumed from the wallet. Triggered when paid or free currency is deducted according to the consumption priority setting. balance double 0.0 0 ~ 281474976710653 Unused Balance The total unused paid currency balance across all users in this namespace, measured in the configured real-world currency. Used for Funds Settlement Act compliance to track the total outstanding obligation. This value is automatically maintained by the system as deposits and withdrawals occur. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, wallet operations (deposit, withdraw, purchase) are logged for monitoring, auditing, and analysis. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Wallet Wallet Currency in the wallet is managed separately for currency purchased for a fee and currency obtained for free. Currency purchased for a fee is further managed by the unit price at the time of purchase, allowing for refunds in the event of service termination, or to determine if the balance is sufficient to meet the requirements of the Funds Settlement Act. The wallet has slots and each slot has a different balance. If balances cannot be shared across platforms, they can be managed separately by using different slots for each platform. Currency acquired for free can also be shared across all platforms. Details  walletId string * ~ 1024 chars Wallet A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. paid int 0 0 ~ 2147483646 Paid Currency Amount The total amount of paid (purchased) currency in this wallet slot. This is the sum of all WalletDetail entries with a non-zero unit price. Increased by deposits from store purchases, decreased by withdrawals according to the consumption priority. free int 0 0 ~ 2147483646 Free Currency Amount The total amount of free (granted) currency in this wallet slot. This corresponds to the WalletDetail entry with unit price of 0. When shareFree is enabled on the namespace, this value is synchronized from slot 0 across all wallet slots. detail List [] 0 ~ 1000 items List of Wallet Details A breakdown of currency holdings by unit price (price point). Each entry tracks how many units of currency were acquired at a specific unit price. Free currency is stored with a unit price of 0. Paid currency entries are sorted by descending price during withdrawal. When an entry’s count reaches 0, it is automatically removed from the list. Maximum 1000 entries. shareFree bool false Share Free Currency Whether free currency in this wallet is shared across all slots. This value is inherited from the namespace setting at wallet creation time. When true, free currency is synchronized from slot 0 to all other wallet slots. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Receipt Receipt Receipts are entities that record payment history. Payment history includes not only requests for increases or decreases in billing currency, but also the history of payment transactions on various delivery platforms. Details  receiptId string * ~ 1024 chars Receipt A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server transactionId string  ~ 1024 chars Transaction ID A unique identifier for this transaction. For store purchases, this corresponds to the platform-specific transaction ID (e.g., Apple transaction ID, Google order ID). For deposit and withdraw operations, this is a system-generated identifier. purchaseToken string ~ 4096 chars Purchase Token The purchaseToken from Google Play payment transactions. Used to verify and acknowledge Google Play in-app purchases. Only present for Google Play purchase receipts. userId string  ~ 128 chars User ID type string (enum) enum {   “purchase”,   “deposit”,   “withdraw” }  Receipt Type The type of transaction recorded by this receipt. “purchase” records a store platform purchase (Apple/Google), “deposit” records currency being added to the wallet, and “withdraw” records currency being consumed from the wallet. The available fields differ by type: purchase receipts have contentsId, while deposit/withdraw receipts have slot, price, paid, free, and total. Definition Description “purchase” Purchase “deposit” Deposit “withdraw” Withdraw slot int {type} != “purchase”  0 ~ 100000000 Slot Number The wallet slot that was affected by this deposit or withdraw operation. Only present for deposit and withdraw receipt types. price float {type} != “purchase”  0 ~ 100000.0 Unit Price The unit price of the currency involved in this transaction. A value of 0 indicates free currency. Only present for deposit and withdraw receipt types. paid int {type} != “purchase”  0 ~ 2147483646 Paid Currency The amount of paid currency involved in this transaction. For deposits, this is the quantity of paid currency added. For withdrawals, this is the quantity of paid currency consumed. Only present for deposit and withdraw receipt types. free int {type} != “purchase”  0 ~ 2147483646 Free Currency The amount of free currency involved in this transaction. For deposits, this is the quantity of free currency added. For withdrawals, this is the quantity of free currency consumed. Only present for deposit and withdraw receipt types. total int {type} != “purchase”  0 ~ 2147483646 Total The total amount of currency (paid + free) involved in this transaction. Only present for deposit and withdraw receipt types. contentsId string {type} == “purchase” ~ 1024 chars Contents ID The product identifier of the item sold on the store platform (Apple AppStore or Google Play). Corresponds to the Apple App Store product ID or Google Play product ID. Only present for purchase receipt types. * Enabled only if type is “purchase” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision WalletDetail Wallet Detail Represents a price-point entry within a wallet, tracking the quantity of currency acquired at a specific unit price. Free currency is represented with a price of 0, while paid currency has a positive unit price corresponding to the real-world purchase cost. This granularity enables accurate refund calculations and Funds Settlement Act compliance by knowing exactly how much was paid for each unit of currency. Details  price float  0 ~ 100000.0 Unit Price The real-world price per unit of currency at the time of purchase. A value of 0 indicates free currency. Positive values represent paid currency with the unit price in the namespace’s configured currency (JPY, USD, TWD). Used for total price calculation (unit price x count) and per-unit price computation during withdrawals. count int  0 ~ 2147483646 Count The quantity of currency held at this unit price. Increased by deposits and decreased by withdrawals. When the count reaches 0, this detail entry is automatically removed from the wallet. During withdrawal, currency is consumed from detail entries according to the namespace’s consumption priority (highest-priced first or free first). Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing money operations. priority string (enum) enum {   “free”,   “paid” }  Consumption Priority Determines the order in which paid and free currency is consumed when withdrawing from the wallet. When set to “free”, free currency (price=0) is consumed first, then paid currency from the highest unit price. When set to “paid”, paid currency is consumed first starting from the highest unit price, then free currency. Definition Description “free” Prioritize the use of free currency “paid” Prioritize the use of paid currency shareFree bool  Share Free Currency Whether free currency is shared across all wallet slots. When enabled, free currency balances are synchronized from slot 0 to all other slots, allowing players on different platforms to share the same free currency pool. Paid currency always remains separate per slot regardless of this setting. currency string (enum) enum {   “JPY”,   “USD”,   “TWD” }  Currency Type The real-world currency used for pricing and Funds Settlement Act compliance calculations. This determines the unit of measurement for tracking paid currency values and calculating refund obligations. Cannot be changed after namespace creation. Definition Description “JPY” JPY “USD” USD “TWD” TWD appleKey string ~ 1024 chars Apple AppStore Bundle ID The Bundle ID of your iOS app, used to verify Apple AppStore purchase receipts. Required when accepting in-app purchases from iOS devices. googleKey string ~ 5120 chars Google PlayStore Private Key The service account private key for Google Play, used to verify Google Play purchase receipts. Required when accepting in-app purchases from Android devices. enableFakeReceipt bool false Enable Fake Receipt Whether to accept fake purchase receipts generated by Unity Editor for testing purposes. Should only be enabled in development/test environments and must be disabled in production to prevent unauthorized currency grants. Defaults to false. createWalletScript ScriptSetting Create Wallet Script Script to run when a new wallet is created for the first time. Wallets are auto-created on first access, so this script triggers when a player first interacts with the currency system. depositScript ScriptSetting Deposit Script Script to run when currency is added to the wallet. Triggered for both paid currency deposits (from store purchases) and free currency grants. withdrawScript ScriptSetting Withdraw Script Script to run when currency is consumed from the wallet. Triggered when paid or free currency is deducted according to the consumption priority setting. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, wallet operations (deposit, withdraw, purchase) are logged for monitoring, auditing, and analysis. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing money operations. priority string (enum) enum {   “free”,   “paid” }  Consumption Priority Determines the order in which paid and free currency is consumed when withdrawing from the wallet. When set to “free”, free currency (price=0) is consumed first, then paid currency from the highest unit price. When set to “paid”, paid currency is consumed first starting from the highest unit price, then free currency. Definition Description “free” Prioritize the use of free currency “paid” Prioritize the use of paid currency appleKey string ~ 1024 chars Apple AppStore Bundle ID The Bundle ID of your iOS app, used to verify Apple AppStore purchase receipts. Required when accepting in-app purchases from iOS devices. googleKey string ~ 5120 chars Google PlayStore Private Key The service account private key for Google Play, used to verify Google Play purchase receipts. Required when accepting in-app purchases from Android devices. enableFakeReceipt bool false Enable Fake Receipt Whether to accept fake purchase receipts generated by Unity Editor for testing purposes. Should only be enabled in development/test environments and must be disabled in production to prevent unauthorized currency grants. Defaults to false. createWalletScript ScriptSetting Create Wallet Script Script to run when a new wallet is created for the first time. Wallets are auto-created on first access, so this script triggers when a player first interacts with the currency system. depositScript ScriptSetting Deposit Script Script to run when currency is added to the wallet. Triggered for both paid currency deposits (from store purchases) and free currency grants. withdrawScript ScriptSetting Withdraw Script Script to run when currency is consumed from the wallet. Triggered when paid or free currency is deducted according to the consumption priority setting. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, wallet operations (deposit, withdraw, purchase) are logged for monitoring, auditing, and analysis. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the cleaning of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeWallets Get a list of wallets Retrieves a paginated list of wallet slots for the requesting user. Each wallet slot manages a separate balance with paid and free currency tracked independently. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Wallets nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeWalletsByUserId Get a list of Wallets by specifying a user ID Retrieves a paginated list of wallet slots for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Wallets nextPageToken string Page token to retrieve the rest of the listing Implementation Example getWallet Get Wallet Retrieves the wallet for the specified slot for the requesting user, including the paid and free currency balances. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. Result Type Description item Wallet Wallet Implementation Example getWalletByUserId Get Wallet by specifying a user ID Retrieves the wallet for the specified slot for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Wallet Implementation Example depositByUserId Deposit balance to wallet by specifying a user ID Adds the specified amount of currency to the wallet for the specified user. If the price is 0, it is treated as free currency; otherwise, it is treated as paid currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. price float  0 ~ 100000.0 Purchase Price count int  1 ~ 2147483646 Quantity of premium currency to be granted timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Wallet after deposit Implementation Example withdraw Consume balance from wallet Withdraws the specified amount of currency from the wallet for the requesting user. If paidOnly is false, free currency is consumed first, then paid currency. If paidOnly is true, only paid currency is consumed. The response includes the price of the consumed currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. count int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency Result Type Description item Wallet Post-withdraw Wallet price float Price of currency consumed Implementation Example withdrawByUserId Consume balance from wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. count int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Post-withdraw Wallet price float Price of currency consumed Implementation Example describeReceipts Get a list of receipts Retrieves a paginated list of purchase receipts within the specified date range. Can optionally filter by user ID and wallet slot. Useful for auditing purchase history and verifying transactions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int 0 ~ 100000000 Slot begin long The absolute time 30 days prior to the current time Search start date and time end long Current time Search end date and time 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Receipts nextPageToken string Page token to retrieve the rest of the listing Implementation Example getByUserIdAndTransactionId Get receipt by specifying user ID and transaction ID Retrieves a specific purchase receipt by its transaction ID for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID transactionId string  ~ 1024 chars Transaction ID A unique identifier for this transaction. For store purchases, this corresponds to the platform-specific transaction ID (e.g., Apple transaction ID, Google order ID). For deposit and withdraw operations, this is a system-generated identifier. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Receipt Receipt Implementation Example recordReceipt Record receipt Records and validates a purchase receipt from a store platform (Apple App Store / Google Play). The receipt is verified against the platform’s servers to prevent fraud. Duplicate receipts are rejected to prevent replay attacks. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID contentsId string  ~ 1024 chars Content IDs sold on the store platform receipt string  ~ 524288 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Receipt Recorded Receipt Implementation Example revertRecordReceipt Delete receipt record by specifying a user ID Reverts a previously recorded receipt by extracting the transaction ID and deleting the corresponding record. Used for handling refunds or chargebacks from the store platform. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID receipt string  ~ 524288 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Receipt Recorded Receipt Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Money SDK for various programming languages\n","title":"GS2-Money SDK API Reference","url":"/api_reference/money/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when depositing or withdrawing currency. currencyUsagePriority string (enum) enum {   “PrioritizeFree”,   “PrioritizePaid” }  Consumption priority Determines the order in which paid and free currency are consumed when withdrawing from the wallet. “PrioritizeFree” consumes free currency first, while “PrioritizePaid” consumes paid currency first. Definition Description “PrioritizeFree” Prioritize the use of free currency “PrioritizePaid” Prioritize the use of paid currency sharedFreeCurrency bool  Share the free currency with different slots When enabled, free currency balance is shared across all wallet slots (platforms). Paid currency remains separate per slot. This setting can only be configured at namespace creation time and cannot be changed later. platformSetting PlatformSetting  Store platform settings Configuration for each supported store platform (Apple App Store, Google Play, Fake for testing). Includes credentials and keys required for receipt verification on each platform. depositBalanceScript ScriptSetting Script setting to be executed when depositing wallet balance Script Trigger Reference - deposit withdrawBalanceScript ScriptSetting Script setting to be executed when withdrawing wallet balance Script Trigger Reference - withdraw verifyReceiptScript ScriptSetting Script setting to be executed when verifying a receipt Script Trigger Reference - verifyReceipt subscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when subscribing to a new contract(Not called when the user associated with the subscription is changed / Called when re-subscribing after contract expiration) Script Trigger Reference - subscribe renewScript string ~ 1024 chars GS2-Script script GRN to be executed when renewing a contract Script Trigger Reference - renew unsubscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when unsubscribing from a contract(Not called when the user associated with the subscription is changed) Script Trigger Reference - unsubscribe takeOverScript ScriptSetting Script setting to be executed when taking over a contract Script Trigger Reference - takeOver changeSubscriptionStatusNotification NotificationSetting Push notification when the subscription status changes Configures push notifications delivered via GS2-Gateway when a subscription status changes (e.g., activated, renewed, canceled, expired, or revoked). Allows the game client to respond to subscription state transitions in real-time. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for tracking deposits, withdrawals, receipt verifications, and subscription events. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Wallet Wallet Currency in the wallet is managed separately for currency purchased for a fee and currency obtained for free. Currency purchased for a fee is further managed by the unit price at the time of purchase, allowing for refunds in the event of service termination, or to determine if the balance is sufficient to meet the requirements of the Funds Settlement Act. The wallet has slots and each slot has a different balance. If balances cannot be shared across platforms, they can be managed separately by using different slots for each platform. Currency acquired for free can also be shared across all platforms. Details  walletId string * ~ 1024 chars Wallet A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. summary WalletSummary  Wallet Status A summary of the wallet’s current balance, broken down into paid currency, free currency, and total amounts. Calculated from the deposit transactions. depositTransactions List [] 0 ~ 1000 items List of deposit transactions Records of all deposits into this wallet. Each transaction tracks the purchase price, currency code, quantity, and deposit time. Paid deposits (price \u003e 0) are managed per unit price for refund calculation and regulatory compliance. sharedFreeCurrency bool  Share free currency Indicates whether the free currency in this wallet is shared across all slots. Inherited from the namespace setting at wallet creation time. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Event Event Event are entities that record payment history. Payment history includes not only requests for increases or decreases in billing currency, but also the history of payment transactions on various delivery platforms. Details  eventId string * ~ 1024 chars Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server transactionId string  ~ 1024 chars Transaction ID The unique identifier for this payment event. Corresponds to the store platform’s transaction ID for receipt verification events. userId string  ~ 128 chars User ID eventType string (enum) enum {   “VerifyReceipt”,   “Deposit”,   “Withdraw”,   “Refund” }  Event Type The type of payment event. “VerifyReceipt” records store receipt verification, “Deposit” records currency additions, “Withdraw” records currency consumption, and “Refund” records refund processing. Definition Description “VerifyReceipt” Verify Receipt “Deposit” Deposit “Withdraw” Withdraw “Refund” Refunded verifyReceiptEvent VerifyReceiptEvent Verify Receipt Event Details of the receipt verification event. Set when eventType is “VerifyReceipt”. Contains the store content name, platform, and platform-specific verification results. depositEvent DepositEvent Deposit Event Details of the deposit event. Set when eventType is “Deposit”. Contains the wallet slot, deposit transactions, and resulting wallet status. withdrawEvent WithdrawEvent Withdraw Event Details of the withdraw event. Set when eventType is “Withdraw”. Contains the wallet slot, withdrawal details, and resulting wallet status. refundEvent RefundEvent Refund Event Details of the refund event. Set when eventType is “Refund”. Contains the store content name, platform, and platform-specific refund information. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscribeTransaction Subscription purchase information Represents a subscription purchase record from a store platform. Tracks the detailed subscription status through its lifecycle including active, trial, intro offer, grace period, canceled, expired, and revoked states. Each transaction is linked to a specific store platform and user. Details  subscribeTransactionId string * ~ 1024 chars Subscription Transaction A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server contentName string  ~ 128 chars Store Subscription Content Model name transactionId string  ~ 1024 chars Transaction ID The unique transaction identifier assigned by the store platform. Used to prevent duplicate processing of the same purchase. store string (enum) enum {   “AppleAppStore”,   “GooglePlay”,   “fake” }  Store The store platform where the purchase was made. Determines which verification method is used for receipt validation. Definition Description “AppleAppStore” Apple App Store “GooglePlay” Google Play “fake” Fake userId string ~ 128 chars User ID statusDetail string (enum) enum {   “active@active”,   “active@converted_from_trial”,   “active@in_trial”,   “active@in_intro_offer”,   “grace@canceled”,   “grace@grace_period”,   “grace@on_hold”,   “inactive@expired”,   “inactive@revoked” }  Status The detailed subscription status. Prefixed with the simplified category (active/grace/inactive) followed by the specific state. Active states indicate the subscription is usable; grace states indicate payment issues but temporary access; inactive states indicate the subscription is no longer valid. Definition Description “active@active” Active “active@converted_from_trial” Converted from free trial to paid plan “active@in_trial” In free trial “active@in_intro_offer” In introductory offer “grace@canceled” User has manually canceled “grace@grace_period” The payment failed, but it is within the grace period. “grace@on_hold” Payment has failed. If payment is not completed within a specified period, the service will be unavailable. “inactive@expired” Subscription has expired “inactive@revoked” Subscription has been revoked expiresAt long  Expiration time The timestamp at which this subscription transaction expires. Updated when the subscription is renewed by the store platform. lastAllocatedAt long Last time allocated to user The timestamp when this subscription transaction was last assigned to a user. Used with reallocateSpanDays to determine if the subscription can be reassigned to a different user. lastTakeOverAt long Last time taken over by user The timestamp when the user associated with this subscription was last changed (taken over). Tracks account transfer history for the subscription. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscriptionStatus Subscription status Tracks a user’s subscription contract status for a specific subscription content. Provides a simplified active/inactive status derived from the detailed subscription transaction states, along with the expiration time and the list of associated subscription transactions. Details  userId string ~ 128 chars User ID contentName string  ~ 128 chars Store Subscription Content Model name status string (enum) enum {   “active”,   “inactive” }  Status The simplified subscription status. “active” includes active, trial, intro offer, and grace period states. “inactive” includes expired and revoked states. Definition Description “active” Active “inactive” Inactive expiresAt long  Expiration time The timestamp at which the subscription expires. Updated when the subscription is renewed or its status changes. detail List [] 0 ~ 100 items Subscription status details The list of subscription transactions associated with this subscription. Each transaction represents a purchase record from a store platform with detailed status information (active, trial, grace period, expired, revoked, etc.). RefundHistory Refund history information Records a refund event with the date, user, and details of the refund. Tracks refund transactions processed by store platforms (Apple App Store, Google Play). Details  refundHistoryId string * ~ 1024 chars Subscription Transaction A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server transactionId string  ~ 1024 chars Transaction ID The unique transaction identifier assigned by the store platform. Used to prevent duplicate processing of the same purchase. year int  2000 ~ 3000 Year month int  1 ~ 12 Month day int  1 ~ 31 Day userId string ~ 128 chars User ID detail RefundEvent  Refund event information createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server DailyTransactionHistory Daily Transaction History Aggregates daily transaction data including total deposit amounts (revenue), withdrawal amounts (consumption), issued currency count, and consumed currency count, broken down by currency code. Used for financial reporting and monitoring. Details  dailyTransactionHistoryId string * ~ 1024 chars Transaction History of Daily Transactions A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server year int  2000 ~ 3000 Year month int  1 ~ 12 Month day int  1 ~ 31 Day currency string  ~ 8 chars Currency Code depositAmount double 0 0 ~ 281474976710654 Deposit Amount The total real-money amount deposited (revenue) on this day, in the specified currency. withdrawAmount double 0 0 ~ 281474976710654 Withdraw Amount The total real-money equivalent of currency consumed (withdrawn) on this day, calculated from the per-unit price of each consumed deposit transaction. issueCount long 0 0 ~ 9223372036854775805 Issue Count The total number of virtual currency units deposited (issued) on this day, including both paid and free currency. consumeCount long 0 0 ~ 9223372036854775805 Consume Count The total number of virtual currency units consumed (withdrawn) on this day. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision UnusedBalance Unused Balance Entity that holds the Unused Balance of billing currency for each currency. Details  unusedBalanceId string * ~ 1024 chars Unused Balance A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server currency string  ~ 8 chars Currency Code The ISO currency code (e.g., “JPY”, “USD”) for which the unused balance is tracked. balance double  0 ~ 16777214 Unused balance The total monetary value of paid currency that remains unused across all users, denominated in the specified currency. Used for compliance with the Funds Settlement Act and similar regulations. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision StoreContentModel Store Content Model This is a model for storing content from various store platforms. Details  storeContentModelId string * ~ 1024 chars Store Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Content Model name metadata string ~ 1024 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. appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. StoreSubscriptionContentModel Store Subscription Content Model This is a model for storing subscription-based content from various store platforms. Details  storeSubscriptionContentModelId string * ~ 1024 chars Subscription Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Subscription Content Model name metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Enabled only if triggerExtendMode is “rollupHour” reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. Receipt Receipt of store platform Represents a purchase receipt from a store platform (Apple App Store, Google Play, or Fake for testing). Contains the transaction ID and payload data needed for server-side receipt verification. Details  Store string (enum) enum {   “AppleAppStore”,   “GooglePlay”,   “fake” }  Store The store platform where the purchase was made. Determines which verification method is used for receipt validation. Definition Description “AppleAppStore” Apple App Store “GooglePlay” Google Play “fake” Fake TransactionID string  ~ 1024 chars Transaction ID The unique transaction identifier assigned by the store platform. Used to prevent duplicate processing of the same purchase. Payload string  ~ 1048576 chars Payload The receipt data from the store platform. The format varies by platform: for Apple App Store, this is the transaction receipt; for Google Play, this is the purchase token and related data. PlatformSetting Platform Setting Aggregates the settings for all supported store platforms. Contains configuration for Apple App Store, Google Play, and Fake (for testing in Unity Editor). Each platform setting includes the credentials and keys necessary for receipt verification. Details  appleAppStore AppleAppStoreSetting Apple AppStore Setting Credentials for Apple App Store receipt verification, including bundle ID, shared secret key, issuer ID, key ID, and private key. googlePlay GooglePlaySetting Google Play Setting Credentials for Google Play receipt verification, including the package name and public key for signature verification. fake FakeSetting Fake (Unity Editor) Setting Configuration for accepting fake receipts generated by Unity Editor during development and testing. AppleAppStoreSetting Apple AppStore Setting Configuration for verifying Apple App Store receipts. Contains the credentials required to communicate with Apple’s receipt verification servers, including the bundle ID, shared secret, App Store Connect issuer ID, key ID, and private key. Details  bundleId string ~ 1024 chars Apple AppStore Bundle ID sharedSecretKey string ~ 1024 chars Shared secret key used to encrypt the receipt issued by AppStore Connect issuerId string ~ 1024 chars Issuer ID of in-app purchases registered with AppStore Connect keyId string ~ 1024 chars Key ID registered with Apple privateKeyPem string ~ 10240 chars Private Key received from Apple GooglePlaySetting Google Play Setting Configuration for verifying Google Play receipts. Contains the package name and public key required for validating purchase signatures from Google Play. Details  packageName string ~ 5120 chars Package Name to be distributed on Google Play publicKey string ~ 5120 chars Public key used for signature verification FakeSetting Fake Setting for Debug Configuration for handling fake receipts generated by Unity Editor during development. Controls whether fake receipts are accepted or rejected, allowing developers to test in-app purchase flows without real store platforms. Details  acceptFakeReceipt string (enum) enum {   “Accept”,   “Reject” } “Reject” Whether to allow payments using fake receipts output by Unity Editor Controls acceptance of fake receipts. Should be set to “Accept” during development/testing and “Reject” in production to prevent unauthorized currency deposits. Definition Description “Accept” Accept “Reject” Reject WalletSummary Wallet Status A summary view of a wallet’s currency balance, separating paid and free amounts. Calculated by aggregating all deposit transactions in the wallet based on their price (paid if price \u003e 0, free if price = 0). Details  paid int 0 0 ~ 2147483646 Count of paid currency The total amount of currency that was purchased with real money (deposit transactions with price \u003e 0). free int 0 0 ~ 2147483646 Count of free currency The total amount of currency obtained for free (deposit transactions with price = 0), such as login bonuses or event rewards. total int 0 0 ~ 2147483646 Total The total currency balance (paid + free). Represents the overall available amount in the wallet. DepositTransaction Deposit Transaction Represents a single deposit record in the wallet. Paid deposits (price \u003e 0) are tracked per unit price to enable accurate refund calculations and compliance with the Funds Settlement Act. Free deposits (price = 0) are tracked separately. When withdrawing, deposit transactions are consumed based on the namespace’s currency usage priority. Details  price double  0.0 ~ 100000000.0 Purchase Price The real-money price paid for this deposit in the local currency. A value of 0 indicates free currency. Used to calculate per-unit cost for refund purposes. currency string {price} \u003e 0  ~ 8 chars Currency Code The ISO currency code (e.g., “JPY”, “USD”) of the real-money payment. Only applicable for paid deposits (price \u003e 0). * Required if price is greater than 0 count int  0 ~ 2147483646 Quantity of premium currency The number of virtual currency units in this deposit. Decreases as currency is withdrawn from the wallet. depositedAt long Deposit Date The timestamp when this deposit was made. VerifyReceiptEvent Verify Receipt Event Records the details of a store receipt verification, including which store content was verified, the platform used, and platform-specific verification results. Details  contentName string  ~ 128 chars Store Content Model name platform string (enum) enum {   “AppleAppStore”,   “GooglePlay”,   “fake” }  Store Platform The store platform from which the receipt was issued. Determines which verification flow was used. Definition Description “AppleAppStore” Apple AppStore “GooglePlay” Google Play “fake” Fake appleAppStoreVerifyReceiptEvent AppleAppStoreVerifyReceiptEvent Apple AppStore Verify Receipt Event Verification result from the Apple App Store. Contains the environment (sandbox or production) information. Set when platform is “AppleAppStore”. googlePlayVerifyReceiptEvent GooglePlayVerifyReceiptEvent Google Play Verify Receipt Event Verification result from Google Play. Contains the purchase token. Set when platform is “GooglePlay”. DepositEvent Deposit Event Records the details of a currency deposit into a wallet, including the deposit transactions and the wallet’s status after the deposit. Details  slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. depositTransactions List [] 0 ~ 1000 items List of deposit transactions The deposit transactions that were added to the wallet in this event. status WalletSummary  Wallet Status The wallet’s balance summary (paid, free, total) after the deposit was applied. WithdrawEvent Withdraw Event Records the details of a currency withdrawal from a wallet, including the breakdown of consumed deposit transactions and the wallet’s status after the withdrawal. Details  slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. withdrawDetails List [] 0 ~ 1000 items List of details of the withdrawn wallet The breakdown of deposit transactions from which currency was consumed. Shows which deposits (paid or free, at what unit price) were drawn from. status WalletSummary  Wallet Status The wallet’s balance summary (paid, free, total) after the withdrawal was applied. RefundEvent Refund Event Records the details of a refund event, including which store content was refunded, the platform where the refund was processed, and platform-specific refund information. Details  contentName string  ~ 128 chars Store Content Model name platform string (enum) enum {   “AppleAppStore”,   “GooglePlay”,   “fake” }  Store Platform The store platform from which the refund was issued. Definition Description “AppleAppStore” Apple AppStore “GooglePlay” Google Play “fake” Fake appleAppStoreRefundEvent AppleAppStoreVerifyReceiptEvent Apple AppStore Verify Receipt Event googlePlayRefundEvent GooglePlayVerifyReceiptEvent Google Play Verify Receipt Event AppleAppStoreVerifyReceiptEvent Apple AppStore Receipt Contains the result of an Apple App Store receipt verification, including the environment (sandbox or production) in which the purchase was made. Details  environment string (enum) enum {   “sandbox”,   “production” }  Environment The Apple App Store environment where the receipt was generated. “sandbox” indicates a test purchase, “production” indicates a real purchase. Definition Description “sandbox” Sandbox “production” Production GooglePlayVerifyReceiptEvent Google Play Receipt Verification Event Contains the result of a Google Play receipt verification, including the purchase token used to validate the purchase. Details  purchaseToken string ~ 4096 chars Purchase Token The purchase token returned by Google Play after a successful purchase. Used to verify and acknowledge the purchase with Google Play’s servers. AppleAppStoreContent Content of Apple AppStore Contains the Apple App Store product ID that corresponds to an in-app purchase product. Used to match receipts during verification. Details  productId string ~ 1024 chars Product ID The Apple App Store product identifier registered in App Store Connect for this in-app purchase item. GooglePlayContent Content of Google Play Contains the Google Play product ID that corresponds to an in-app purchase product. Used to match receipts during verification. Details  productId string ~ 1024 chars Product ID The Google Play product identifier registered in Google Play Console for this in-app purchase item. AppleAppStoreSubscriptionContent Subscription content of Apple AppStore Contains the Apple App Store subscription group identifier for subscription-based products. Used to manage and verify auto-renewable subscriptions. Details  subscriptionGroupIdentifier string ~ 64 chars Subscription Group ID The subscription group identifier registered in App Store Connect. Subscriptions within the same group are mutually exclusive, meaning a user can only subscribe to one at a time. GooglePlaySubscriptionContent Google Play Subscription Content Contains the Google Play product ID for subscription-based products. Used to manage and verify auto-renewable subscriptions on Google Play. Details  productId string ~ 1024 chars Product ID GooglePlayRealtimeNotificationMessage RTDN Message Represents a Google Play Real-Time Developer Notification (RTDN) message. RTDN messages are sent by Google Play to notify the server of subscription state changes such as renewals, cancellations, and expirations. Details  data string  ~ 1048576 chars Data The base64-encoded notification payload containing subscription state change information from Google Play. messageId string  ~ 1024 chars Message ID The unique identifier for this RTDN message. Used for deduplication. publishTime string  ~ 1024 chars Publish Time The timestamp when the notification was published, in RFC 3339 format. CurrentModelMaster Currently active Models master data This master data defines the Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Money2 Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data StoreContentModelMaster Store Content Model Master The Store Content Model is a model that stores content from various store platforms. Details  storeContentModelId string * ~ 1024 chars Content Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision StoreSubscriptionContentModelMaster Store Subscription Content Model Master The Store Subscription Content Model is a model that stores subscription-based content from various store platforms. Details  storeSubscriptionContentModelId string * ~ 1024 chars Subscription Content Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Subscription Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Enabled only if triggerExtendMode is “rollupHour” appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). currencyUsagePriority string (enum) enum {   “PrioritizeFree”,   “PrioritizePaid” }  Consumption priority Determines the order in which paid and free currency are consumed when withdrawing from the wallet. “PrioritizeFree” consumes free currency first, while “PrioritizePaid” consumes paid currency first. Definition Description “PrioritizeFree” Prioritize the use of free currency “PrioritizePaid” Prioritize the use of paid currency description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when depositing or withdrawing currency. sharedFreeCurrency bool  Share the free currency with different slots When enabled, free currency balance is shared across all wallet slots (platforms). Paid currency remains separate per slot. This setting can only be configured at namespace creation time and cannot be changed later. platformSetting PlatformSetting  Store platform settings Configuration for each supported store platform (Apple App Store, Google Play, Fake for testing). Includes credentials and keys required for receipt verification on each platform. depositBalanceScript ScriptSetting Script setting to be executed when depositing wallet balance Script Trigger Reference - deposit withdrawBalanceScript ScriptSetting Script setting to be executed when withdrawing wallet balance Script Trigger Reference - withdraw verifyReceiptScript ScriptSetting Script setting to be executed when verifying a receipt Script Trigger Reference - verifyReceipt subscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when subscribing to a new contract(Not called when the user associated with the subscription is changed / Called when re-subscribing after contract expiration) Script Trigger Reference - subscribe renewScript string ~ 1024 chars GS2-Script script GRN to be executed when renewing a contract Script Trigger Reference - renew unsubscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when unsubscribing from a contract(Not called when the user associated with the subscription is changed) Script Trigger Reference - unsubscribe takeOverScript ScriptSetting Script setting to be executed when taking over a contract Script Trigger Reference - takeOver changeSubscriptionStatusNotification NotificationSetting Push notification when the subscription status changes Configures push notifications delivered via GS2-Gateway when a subscription status changes (e.g., activated, renewed, canceled, expired, or revoked). Allows the game client to respond to subscription state transitions in real-time. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for tracking deposits, withdrawals, receipt verifications, and subscription events. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). currencyUsagePriority string (enum) enum {   “PrioritizeFree”,   “PrioritizePaid” }  Consumption priority Determines the order in which paid and free currency are consumed when withdrawing from the wallet. “PrioritizeFree” consumes free currency first, while “PrioritizePaid” consumes paid currency first. Definition Description “PrioritizeFree” Prioritize the use of free currency “PrioritizePaid” Prioritize the use of paid currency description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when depositing or withdrawing currency. platformSetting PlatformSetting  Store platform settings Configuration for each supported store platform (Apple App Store, Google Play, Fake for testing). Includes credentials and keys required for receipt verification on each platform. depositBalanceScript ScriptSetting Script setting to be executed when depositing wallet balance Script Trigger Reference - deposit withdrawBalanceScript ScriptSetting Script setting to be executed when withdrawing wallet balance Script Trigger Reference - withdraw verifyReceiptScript ScriptSetting Script setting to be executed when verifying a receipt Script Trigger Reference - verifyReceipt subscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when subscribing to a new contract(Not called when the user associated with the subscription is changed / Called when re-subscribing after contract expiration) Script Trigger Reference - subscribe renewScript string ~ 1024 chars GS2-Script script GRN to be executed when renewing a contract Script Trigger Reference - renew unsubscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when unsubscribing from a contract(Not called when the user associated with the subscription is changed) Script Trigger Reference - unsubscribe takeOverScript ScriptSetting Script setting to be executed when taking over a contract Script Trigger Reference - takeOver changeSubscriptionStatusNotification NotificationSetting Push notification when the subscription status changes Configures push notifications delivered via GS2-Gateway when a subscription status changes (e.g., activated, renewed, canceled, expired, or revoked). Allows the game client to respond to subscription state transitions in real-time. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for tracking deposits, withdrawals, receipt verifications, and subscription events. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeWallets Get a list of wallets Retrieves a paginated list of wallets for the requesting user. Each wallet manages a separate balance with paid and free currency tracked independently. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Wallets nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeWalletsByUserId Get a list of wallets by specifying a user ID Retrieves a paginated list of wallets for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Wallets nextPageToken string Page token to retrieve the rest of the listing Implementation Example getWallet Get Wallet Retrieves the wallet for the specified slot for the requesting user, including the paid and free currency balances. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. Result Type Description item Wallet Wallet Implementation Example getWalletByUserId Get Wallet by specifying a user ID Retrieves the wallet for the specified slot for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Wallet Implementation Example depositByUserId Deposit balance to Wallet by specifying a user ID Adds the specified deposit transactions to the wallet for the specified user. An event log is recorded for each deposit transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. depositTransactions List  1 ~ 1000 items List of Deposit transactions timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Wallet after deposit Implementation Example withdraw Withdraw balance from wallet Withdraws the specified amount of currency from the wallet for the requesting user. If paidOnly is false, free currency is consumed first, then paid currency. If paidOnly is true, only paid currency is consumed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency Result Type Description item Wallet Post-withdraw Wallet withdrawTransactions List List of consumed deposit transactions Implementation Example withdrawByUserId Withdraw balance from Wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Wallet Post-withdraw Wallet withdrawTransactions List List of consumed deposit transactions Implementation Example describeEventsByUserId Get a list of Events Retrieves a paginated list of purchase events for the specified user within the specified date range. The default date range is the last 30 days. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID begin long The absolute time 30 days prior to the current time Search start date and time end long Current time Search end date and time 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Events nextPageToken string Page token to retrieve the rest of the listing Implementation Example getEventByTransactionId Get Event by specifying transaction ID Retrieves a specific purchase event by its transaction ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). transactionId string  ~ 1024 chars Transaction ID The unique identifier for this payment event. Corresponds to the store platform’s transaction ID for receipt verification events. Result Type Description item Event Event Implementation Example verifyReceipt Record receipt Verifies a purchase receipt against the store content model and records it as used. An event log is recorded and the verify receipt script configured in the namespace is executed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token contentName string  ~ 128 chars Store Content Model name receipt Receipt  Receipt Result Type Description item Event Event Implementation Example verifyReceiptByUserId Mark a receipt as used by specifying a user ID Verifies a purchase receipt for the specified user and records it as used. An event log is recorded and the verify receipt script configured in the namespace is executed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID contentName string  ~ 128 chars Store Content Model name receipt Receipt  Receipt timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Event Event Implementation Example describeSubscriptionStatuses Get a list of Store Subscription Statuses Retrieves the subscription statuses for all subscription content models for the requesting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token Result Type Description items List List of Subscription statuses Implementation Example describeSubscriptionStatusesByUserId Get a list of Store Subscription Statuses by specifying a user ID Retrieves the subscription statuses for all subscription content models for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Subscription statuses Implementation Example getSubscriptionStatus Get subscription status Retrieves the subscription status for the specified content for the requesting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token contentName string  ~ 128 chars Store Subscription Content Model name Result Type Description item SubscriptionStatus Subscription status Implementation Example getSubscriptionStatusByUserId Get subscription status by specifying a user ID Retrieves the subscription status for the specified content for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID contentName string  ~ 128 chars Store Subscription Content Model name timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscriptionStatus Subscription status Implementation Example allocateSubscriptionStatus Allocate subscription status from receipt Allocates a subscription to the requesting user by verifying the receipt against the store platform (Apple App Store / Google Play). If the subscription is newly allocated, the subscribe script configured in the namespace is executed and the schedule trigger is updated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token receipt string  ~ 1024 chars Receipt Result Type Description item SubscriptionStatus Subscription status Implementation Example allocateSubscriptionStatusByUserId Allocate subscription status by specifying a user ID from receipt Allocates a subscription to the specified user by verifying the receipt against the store platform. If the subscription is already allocated to a different user, an AlreadyUsed error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID receipt string  ~ 1024 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscriptionStatus Subscription status Implementation Example takeoverSubscriptionStatus Take over the subscription status of a subscription that is already assigned to another user Transfers a subscription that is currently assigned to another user to the requesting user. The take over script configured in the namespace is executed, and the schedule trigger is updated for both the old and new users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token receipt string  ~ 1024 chars Receipt Result Type Description item SubscriptionStatus Subscription status Implementation Example takeoverSubscriptionStatusByUserId Take over the subscription status of a subscription that is already assigned to another user by specifying a user ID Transfers a subscription that is currently assigned to another user to the specified user. The take over script is executed and subscription triggers are updated for both users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID receipt string  ~ 1024 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscriptionStatus Subscription status Implementation Example describeRefundHistoriesByUserId Get a list of store refund history by specifying a user ID Retrieves a paginated list of refund history records for the specified user. Each record contains details about the refund event, including the content name and platform information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of refund history nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeRefundHistoriesByDate Get a list of store refund history by year and month Retrieves a paginated list of refund history records filtered by year and month. Can optionally filter by day. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). year int  2000 ~ 3000 Year month int  1 ~ 12 Month day int 1 ~ 31 Day 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 List of refund history nextPageToken string Page token to retrieve the rest of the listing Implementation Example getRefundHistory Get refund history by specifying a transaction ID Retrieves a specific refund history record by its transaction ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). transactionId string  ~ 1024 chars Transaction ID The unique transaction identifier assigned by the store platform. Used to prevent duplicate processing of the same purchase. Result Type Description item RefundHistory Subscription status Implementation Example describeDailyTransactionHistoriesByCurrency Get a list of daily transaction histories by specifying currency Retrieves a paginated list of daily transaction histories filtered by the specified currency and year. Can optionally filter by month. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). currency string  ~ 8 chars Currency Code year int  2000 ~ 3000 Year month int 1 ~ 12 Month 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 List of Daily Transaction Histories nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeDailyTransactionHistories Get a list of daily transaction histories Retrieves a paginated list of daily transaction histories for the specified year. Can optionally filter by month, and further by day when a month is specified. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). year int  2000 ~ 3000 Year month int 1 ~ 12 Month day int {month} \u003e 0 1 ~ 31 Day 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 List of Daily Transaction Histories nextPageToken string Page token to retrieve the rest of the listing Implementation Example getDailyTransactionHistory Get daily transaction history by specifying date and currency Retrieves a specific daily transaction history record for the specified date and currency. The record contains deposit/withdrawal amounts and issue/consume counts for that day. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). year int  2000 ~ 3000 Year month int  1 ~ 12 Month day int  1 ~ 31 Day currency string  ~ 8 chars Currency Code Result Type Description item DailyTransactionHistory DailyTransactionHistory Implementation Example describeUnusedBalances Get a list of Unused Balances Retrieves a paginated list of unused balance records for the namespace. Each record represents the unused paid currency balance for a specific currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Unused Balances nextPageToken string Page token to retrieve the rest of the listing Implementation Example getUnusedBalance Get Unused Balance by specifying a currency Retrieves the unused balance for the specified currency. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). currency string  ~ 8 chars Currency Code The ISO currency code (e.g., “JPY”, “USD”) for which the unused balance is tracked. Result Type Description item UnusedBalance Unused Balance Implementation Example describeStoreContentModels Get a list of Store Content Model Retrieves the list of currently active store content models. These models define the purchasable content items with their platform-specific product identifiers. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Store Content Models Implementation Example getStoreContentModel Get Store Content Model Retrieves the specified store content model including its Apple App Store and Google Play configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Content Model name Result Type Description item StoreContentModel Store Content Model Implementation Example describeStoreSubscriptionContentModels Get a list of Store Subscription Content Models Retrieves the list of currently active store subscription content models. These models define the subscription products with their platform-specific settings and scheduling parameters. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Store Subscription Content Models Implementation Example getStoreSubscriptionContentModel Get Store Subscription Content Model Retrieves the specified store subscription content model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Subscription Content Model name Result Type Description item StoreSubscriptionContentModel Store Subscription Content Model Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently registered model masters (store content models and subscription content models) in an activatable master data format. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Master data that can be activated Implementation Example getCurrentModelMaster Get currently active Models master data Retrieves the currently active model master data including store content models and subscription content models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentModelMaster Updated master data of the currently active Models Implementation Example preUpdateCurrentModelMaster Update currently active Models master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentModelMaster Update currently active Models master data Updates the currently active model master data. Supports both direct update mode and pre-upload mode for handling large master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentModelMaster Updated master data of the currently active Models Implementation Example updateCurrentModelMasterFromGitHub Update currently active Models master data from GitHub Updates the currently active model master data by checking out master data from a GitHub repository using the specified checkout settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentModelMaster Updated master data of the currently active Models Implementation Example describeStoreContentModelMasters Get a list of Store Content Model Masters Retrieves a paginated list of store content model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Store Content name prefix 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 List of Store Content Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createStoreContentModelMaster Create a new store content master Creates a new store content model master with platform-specific settings for Apple App Store and Google Play product identifiers. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Store Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. Result Type Description item StoreContentModelMaster Store Content Master created Implementation Example getStoreContentModelMaster Get Store Content Master Retrieves the specified store content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Content Model name Result Type Description item StoreContentModelMaster Store Content Master Implementation Example updateStoreContentModelMaster Update Store Content Master Updates the specified store content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. Result Type Description item StoreContentModelMaster Store Content Master updated Implementation Example deleteStoreContentModelMaster Delete Store Content Master Deletes the specified store content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Content Model name Result Type Description item StoreContentModelMaster Store Content Master deleted Implementation Example describeStoreSubscriptionContentModelMasters Get a list of Store Subscription Content Model Masters Retrieves a paginated list of store subscription content model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by store subscription content name prefix 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 List of Store Subscription Content Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createStoreSubscriptionContentModelMaster Create a new Store Subscription Content Model Master Creates a new store subscription content model master with scheduling parameters and platform-specific settings for Apple App Store and Google Play. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Store Subscription Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Required if triggerExtendMode is “rollupHour” reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. Result Type Description item StoreSubscriptionContentModelMaster Store Subscription Content Model Master created Implementation Example getStoreSubscriptionContentModelMaster Get Store Subscription Content Model Master Retrieves the specified store subscription content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Subscription Content Model name Result Type Description item StoreSubscriptionContentModelMaster Store Subscription Content Model Master Implementation Example updateStoreSubscriptionContentModelMaster Update Store Subscription Content Model Master Updates the specified store subscription content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Subscription Content Model name description string ~ 1024 chars Description metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Required if triggerExtendMode is “rollupHour” reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. Result Type Description item StoreSubscriptionContentModelMaster Store Subscription Content Model Master updated Implementation Example deleteStoreSubscriptionContentModelMaster Delete Store Subscription Content Model Master Deletes the specified store subscription content model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). contentName string  ~ 128 chars Store Subscription Content Model name Result Type Description item StoreSubscriptionContentModelMaster Store Subscription Content Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Money2 SDK for various programming languages\n","title":"GS2-Money2 SDK API Reference","url":"/api_reference/money2/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description version string ~ 1024 chars Version The current version identifier of the deployed news content. Updated automatically when new article data is uploaded or synchronized from a GitHub repository. This value is confidential and not exposed to clients. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, news operations (article retrieval, content generation, cookie issuance, etc.) are logged for monitoring and analysis. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Progress Progress Tracks the progress of generating static HTML content from uploaded Hugo site data. When article data is uploaded or synchronized from GitHub, content is generated for different user segments (patterns). This entity monitors how many patterns have been generated versus the total expected, and collects Output log entries during the process. Details  progressId string * ~ 1024 chars Content generation progress A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server uploadToken string  ~ 1024 chars Upload Token A token identifying the specific upload session that triggered this content generation. Used to correlate the progress tracking with the original upload request. generated int  0 ~ 1000 Generated Count The number of content patterns that have been successfully generated so far. This value increments as each pattern is processed. When it equals patternCount, generation is complete. Maximum 1000. patternCount int  0 ~ 1000 Pattern Count The total number of content patterns (templates) that need to be generated for this upload. Represents the full scope of the generation task. Progress is measured as generated / patternCount. Maximum 1000. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Output Output A log entry produced during the content generation process. Each Output records a message about the progress or result of generating static HTML from Hugo site data. Outputs are associated with a Progress entity. Details  outputId string * ~ 1024 chars Output of content generation progress A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Output Name Maintains a unique name for each output. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each output. text string  ~ 1048576 chars Text The log message text produced during content generation. May contain status messages, error details, or other information about the generation process. Maximum 1MB. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision News News Article Represents a single news article generated from Hugo site data. Each article belongs to a section and content path, and has a title, timestamp, and front matter metadata. Articles can optionally be linked to a GS2-Schedule event to control their display period. The front matter contains additional metadata in JSON format, including an optional weight field for controlling display order. Details  section string  ~ 1024 chars Section Name The section (category) to which this article belongs, corresponding to the Hugo content directory structure. Used to organize articles into logical groups for display. content string  ~ 1024 chars Content The content path identifier for this article within its section. Together with the section, uniquely identifies the article’s location in the Hugo content structure. title string  ~ 1024 chars Article Headline The title of the news article, typically defined in the Hugo front matter. Displayed as the headline when listing articles for the player. scheduleEventId string ~ 1024 chars GS2-Schedule Event A unique resource name assigned to all information handled by GS2\" \u003e GRN timestamp long  Timestamp Unix time, milliseconds frontMatter string  ~ 1024 chars Front Matter Metadata associated with the article in JSON format, originally defined in the Hugo markdown front matter. May contain arbitrary fields such as weight (for controlling display order), tags, categories, and other custom properties. SetCookieRequestEntry Set Cookie Request Entry Represents a cookie key-value pair that must be set in the browser/WebView to access the news article web content. The client must set these cookies before loading the article URLs to ensure authorized access to the content. Details  key string  ~ 128 chars Cookie Key The name of the cookie that must be set for authenticated access to the news content. Maximum 128 characters. value string  ~ 1024 chars Cookie Value The value of the cookie that must be set for authenticated access to the news content. Maximum 1024 characters. View View Represents the difference between the current and previous versions of the news content for a specific user. Contains two lists: contents to be added or updated, and contents to be removed. This delta-based approach enables efficient incremental updates on the client side, avoiding the need to re-download all content on every update. Details  contents List 0 ~ 1000 items Contents to Add/Update The list of content entries that should be added or updated in the client’s local cache. These represent new or modified articles since the last version the user retrieved. Maximum 1000 entries. removeContents List 0 ~ 1000 items Contents to Remove The list of content entries that should be removed from the client’s local cache. These represent articles that have been deleted or are no longer visible since the last version. Maximum 1000 entries. Content Content Represents a content entry used in View definitions to specify which articles to include or exclude. Each Content is identified by a section and content path, and carries front matter metadata in JSON format. The front matter carries metadata in JSON format. Details  section string  ~ 1024 chars Section The section (category) path for this content entry, corresponding to the Hugo content directory structure. content string  ~ 1024 chars Content Path The content path identifier within the section, used to uniquely identify this content entry. Uniqueness within a View is enforced by this field. frontMatter string  ~ 1048576 chars Front Matter Metadata associated with this content entry in JSON format. Contains article properties such as title, date, weight, tags, and other Hugo front matter fields. Can store up to 1MB of metadata. Methods describeNamespaces Get a list of namespaces Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, news operations (article retrieval, content generation, cookie issuance, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, news operations (article retrieval, content generation, cookie issuance, etc.) are logged for monitoring and analysis. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example describeProgresses Get a list of content generation progress Retrieves a paginated list of content generation progress records for the namespace. Each record represents the status of a site generation task. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Content generation progress nextPageToken string Page token to retrieve the rest of the listing Implementation Example getProgress Get content generation progress Retrieves the content generation progress for the specified upload token. Shows the current status and details of the site generation task. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). uploadToken string  ~ 1024 chars Upload Token A token identifying the specific upload session that triggered this content generation. Used to correlate the progress tracking with the original upload request. Result Type Description item Progress Progress Implementation Example describeOutputs Get a list of output of content generation progress Retrieves a paginated list of output logs from the content generation process for the specified upload token. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). uploadToken string  ~ 1024 chars Upload Token A token identifying the specific upload session that triggered this content generation. Used to correlate the progress tracking with the original upload request. 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 List of Output of content generation progress nextPageToken string Page token to retrieve the rest of the listing Implementation Example getOutput Get output of content generation progress Retrieves a specific output log entry from the content generation process by specifying the upload token and output name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). uploadToken string  ~ 1024 chars Upload Token A token identifying the specific upload session that triggered this content generation. Used to correlate the progress tracking with the original upload request. outputName string  UUID ~ 36 chars Output Name Maintains a unique name for each output. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each output. Result Type Description item Output Output Implementation Example describeNews Get a list of News Articles Retrieves the list of news articles for the requesting user. Returns articles along with content hash and template hash for cache validation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of News Articles contentHash string Hash value of News Article data templateHash string Hash value of template data Implementation Example describeNewsByUserId Get a list of News Articles by specifying a user ID Retrieves the list of news articles for the specified user. Returns articles along with content hash and template hash for cache validation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of News Articles contentHash string Hash value of News Article data templateHash string Hash value of template data Implementation Example wantGrant Get the information needed to access the News Article Retrieves the cookies and URLs needed to access news web content for the requesting user. Returns cookies for browser-based access, a browser URL, and a ZIP URL for downloading content without cookies. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of cookies that need to be set in order to access the content browserUrl string URL to access the content zipUrl string URL to access the announcement contents in ZIP format (Cookie setting is not required for access) Implementation Example wantGrantByUserId Get the information necessary to access a News Article by specifying a user ID Retrieves the cookies and URLs needed to access news web content for the specified user. Returns cookies for browser-based access, a browser URL, and a ZIP URL for downloading content without cookies. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of cookies that need to be set in order to access the content browserUrl string URL to access the content zipUrl string URL to access the announcement contents in ZIP format (Cookie setting is not required for access) Implementation Example prepareUpdateCurrentNewsMaster Prepare updates to Currently Active Notice Upload a zip file with compressed site data to the URL included in the response, and After the upload is complete, updateCurrentNewsMaster is called to reflect the results. When uploading a zip file, Content-Type must be application/zip. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload templateUploadUrl string URL used to execute the template upload process Implementation Example updateCurrentNewsMaster Update currently available notices Applies the uploaded site data to generate the news content. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). uploadToken string  ~ 1024 chars Token received in preparation for upload Result Type Description Implementation Example prepareUpdateCurrentNewsMasterFromGitHub Update currently available notices from GitHub Prepares a news content update by checking out site data from a GitHub repository. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description uploadToken string Token used to reflect results after upload Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-News SDK for various programming languages\n","title":"GS2-News SDK API Reference","url":"/api_reference/news/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting quest rewards. startQuestScript ScriptSetting Script setting to be executed when the quest is started Script Trigger Reference - startQuest completeQuestScript ScriptSetting Script setting to be executed when a quest is completed Script Trigger Reference - completeQuest failedQuestScript ScriptSetting Script to run when a quest fails Script Trigger Reference - failedQuest logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking quest start, completion, and failure events. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Progress Quest Progress It is created at the beginning of the quest and deleted at the end. When you exit the application in the middle of an in-game, this data will remain. It is possible to resume the game from the ongoing quest information maintained by the entity. Details  progressId string * ~ 1024 chars Quest Progress A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID transactionId string  UUID ~ 36 chars Transaction ID Unique identifier for the quest transaction. Used to associate the quest progress with the transaction that manages reward distribution. questModelId string  ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN GRN of the quest model currently in progress. Identifies which quest the user is playing, enabling game resume if the application is closed mid-quest. randomSeed long  0 ~ 9223372036854775805 Random Seed Random number seed assigned at quest start. Used to determine the content variation (reward set) selected for this quest attempt, ensuring reproducible results. rewards List [] 0 ~ 1000 items Completion Rewards List of rewards to be granted upon successful quest completion. Determined at quest start based on the content variation selected by the random seed. failedRewards List [] 0 ~ 1000 items Failed Rewards List of rewards to be granted when the quest fails. Determined at quest start, providing consolation rewards or partial cost refunds upon failure. metadata string ~ 256 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision CompletedQuestList Completed Quest List Tracks the quests a user has completed within a quest group. Used to determine prerequisite quest completion and first-clear bonus eligibility. Each quest name is recorded only once regardless of how many times it is cleared. Details  completedQuestListId string * ~ 1024 chars Completed Quest List A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. completeQuestNames List [] 0 ~ 1000 items Completed Quest Names List of quest names that the user has completed within this quest group. Quest names are added upon first completion and are deduplicated. Used to evaluate prerequisite quest conditions and first-clear bonus eligibility. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision QuestGroupModel Quest Group Model A Quest Group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups. Details  questGroupModelId string * ~ 1024 chars Quest Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. quests List [] 0 ~ 1000 items Quests belonging to the group List of quest models that belong to this quest group. Only one quest within the group can be in progress at a time. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. QuestModel Quest Model A Quest Model is an entity that defines the cost required to start a quest and the rewards obtained upon completion. The reward obtained upon completion of the quest can have multiple variations and can be drawn at the start of the quest. For example, the same content can be used to manage the clear flag of a quest, but two types of content can be prepared based on whether or not a rare monster appears. Details  questModelId string * ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. contents List [] 1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. Contents Contents Represents one variation of quest content. Each quest can have multiple content variations with different rewards, and one is selected by weighted random draw at quest start. The metadata supports template variable substitution with user ID and config values. Details  metadata string ~ 256 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. completeAcquireActions List [] 0 ~ 10 items Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. weight int 1 1 ~ 2147483646 Draw Weight The relative weight used in the random selection of this content variation at quest start. Higher values increase the probability of this variation being selected. For example, a variation with weight 9 is 9 times more likely to be selected than one with weight 1. Reward Reward Represents a single reward item determined at quest start. Contains the acquire action to execute, the target resource, and the quantity to grant. Stored in the Progress entity and used to distribute rewards upon quest completion or failure. Details  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 request string  ~ 5242880 chars Request JSON string of the request parameters used when executing the acquire action. Contains the specific details of the reward, such as target namespace, resource name, and quantity. itemId string  ~ 1024 chars Item ID GRN of the resource to be acquired as a reward. Identifies the specific item, currency, or other resource that will be granted to the player. value int  0 ~ 2147483646 Value The quantity of the resource to be granted as a reward. This value can be adjusted dynamically based on game logic. AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentQuestMaster Currently active Quest Model master data This master data defines the Quest Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Quest Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data QuestGroupModelMaster Quest Group Model Master Quest Group Model Master is data used to edit and manage Quest Group Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Quest Group Model actually referenced by the game. A Quest Group is an entity for grouping multiple quests, and only one quest progression can be performed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups. Details  questGroupModelId string * ~ 1024 chars Quest Group Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision QuestModelMaster Quest Model Master Quest Model Master is data used to edit and manage Quest Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Quest Model actually referenced by the game. Quest Model Master is an entity that holds the costs required to start a quest and the rewards obtained upon completion. Multiple variations of completion rewards can be prepared, and a reward variation can be selected at random when the quest begins. For example, even if the quest itself is the same, you can create two content variations depending on whether a rare monster appears. Details  questModelId string * ~ 1024 chars Quest Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server questGroupName string  ~ 128 chars Quest Group Model name name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. contents List  1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting quest rewards. startQuestScript ScriptSetting Script setting to be executed when the quest is started Script Trigger Reference - startQuest completeQuestScript ScriptSetting Script setting to be executed when a quest is completed Script Trigger Reference - completeQuest failedQuestScript ScriptSetting Script to run when a quest fails Script Trigger Reference - failedQuest logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking quest start, completion, and failure events. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting quest rewards. startQuestScript ScriptSetting Script setting to be executed when the quest is started Script Trigger Reference - startQuest completeQuestScript ScriptSetting Script setting to be executed when a quest is completed Script Trigger Reference - completeQuest failedQuestScript ScriptSetting Script to run when a quest fails Script Trigger Reference - failedQuest logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking quest start, completion, and failure events. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeProgressesByUserId Get a list of Quest Progress Retrieves the quest progress for the specified user. A user can have at most one active quest progress at a time per quest group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Quest Progresses nextPageToken string Page token to retrieve the rest of the listing Implementation Example createProgressByUserId Create a new Quest Progress by specifying a user ID Creates a quest progress by looking up the quest model, performing a lottery on the quest content, and starting the quest. If a quest is already in progress, it returns an error unless the force flag is set. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID questModelId string  ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN to Start force bool false If have a quest already started, you can discard it and start it config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Quest Progress Implementation Example getProgress Get quest progress Retrieves the current quest progress along with the associated quest group model and quest model. This provides all information needed to resume or display the quest. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Progress Quest Progress questGroup QuestGroupModel Quest Group Model quest QuestModel Quest Model Implementation Example getProgressByUserId Get Quest Progress by specifying a user ID Retrieves the current quest progress for the specified user along with the associated quest group model and quest model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Quest Progress questGroup QuestGroupModel Quest Group Model quest QuestModel Quest Model Implementation Example start Start Quest Within the same category, a game player can execute one quest at a time. If there is already a quest running in the same category, this API will return an error. By calling the API to retrieve quests in progress, you can get the information you need to resume a quest. You can force a quest to start by specifying true for the force parameter. If the quest is successfully started, a Progress object is responded to. The Progress object responds with some information necessary to execute the quest. transactionId is the unique ID of the running quest. This ID must be specified when reporting the completion of a quest. randomSeed is a random number seed that can be used to determine the contents of the quest. A different random number is dispensed each time you start a quest, so you can use this value as the seed value to keep the game going. Even if an application is forcefully terminated during a quest, it can be resumed under the same conditions. The rewards are the “maximum value” of the rewards and their quantities available for this quest. You can also pass rewards to the quest completion report, where you specify the quantity of items actually obtained during the quest. See the Quest Completion Reporting API documentation for more details. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name questName string  ~ 128 chars Quest Model name accessToken string  ~ 128 chars Access token force bool false If have a quest already started, you can discard it and start it config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example startByUserId Start a quest by specifying a user ID Within the same category, a game player can execute one quest at a time. If there is already a running quest in the same category, this API will return an error. By calling the API to retrieve quests in progress, you can get the information you need to resume a quest. You can force a quest to start by specifying true for the force parameter. If the quest is successfully started, a Progress object is responded to. The Progress object responds with some information necessary to execute the quest. transactionId is the unique ID of the running quest. This ID must be specified when reporting the completion of a quest. randomSeed is a random number seed that can be used to determine the contents of the quest. A different random number is dispensed each time a quest is opened®, so you can use this value as a seed value to keep the game going. Even if an application is forcefully terminated during a quest, it can be resumed under the same conditions. The rewards are the “maximum value” of the rewards and their quantities available for this quest. You can also pass rewards to the quest completion report, where you specify the quantity of items actually obtained during the quest. See the Quest Completion Reporting API documentation for more details. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name questName string  ~ 128 chars Quest Model name userId string  ~ 128 chars User ID force bool false If have a quest already started, you can discard it and start it config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the quest initiation process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example end Completed Quest Of the “maximum” of available rewards and their quantity in the quest received at the start of the quest, the rewards actually obtained in the quest are reported in rewards. isComplete reports whether the quest was completed. If the quest is failed, the rewards value is ignored and the reward for failure set for the quest is given. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rewards List [] 0 ~ 1000 items The actual rewards from the quest isComplete bool  Whether the quest has been completed config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Progress Quest Progress transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example endByUserId Complete quest by specifying a user ID Of the “maximum” of available rewards and their quantity in the quest received at the start of the quest, the rewards actually obtained in the quest are reported in rewards. isComplete reports whether the quest was completed. If the quest is failed, the rewards value is ignored and the reward for failure set for the quest is given. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rewards List [] 0 ~ 1000 items The actual rewards from the quest isComplete bool  Whether the quest has been completed config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Quest Progress transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reward granting process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example deleteProgress Delete quest progress Deletes the current quest progress for the requesting user. This cancels the quest in progress and allows starting a new quest. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Progress Quest Progress Implementation Example deleteProgressByUserId Delete Quest Progress by specifying a user ID Deletes the current quest progress for the specified user. This cancels the quest in progress and allows starting a new quest. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Progress Quest Progress Implementation Example describeCompletedQuestLists Get a list of Completed Quest lists Retrieves a paginated list of completed quest lists for the requesting user. Each entry represents a quest group and the quests completed within it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Completed Quest lists nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeCompletedQuestListsByUserId Get a list of Completed Quest Lists by specifying a user ID Retrieves a paginated list of completed quest lists for the specified user. Each entry represents a quest group and the quests completed within it. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Completed Quest lists nextPageToken string Page token to retrieve the rest of the listing Implementation Example getCompletedQuestList Get Completed Quest List Retrieves the completed quest list for the specified quest group. Contains the names of all quests that the requesting user has completed within the group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. accessToken string  ~ 128 chars Access token Result Type Description item CompletedQuestList Completed Quest List Implementation Example getCompletedQuestListByUserId Get Completed Quest List by specifying a user ID Retrieves the completed quest list for the specified quest group and user. Contains the names of all quests that the user has completed within the group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item CompletedQuestList Completed Quest List Implementation Example deleteCompletedQuestListByUserId Delete Completed Quest List by specifying a user ID Deletes the completed quest list for the specified quest group and user. This resets the completion status for all quests in the group, allowing the user to earn first-clear rewards again. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model Name The name of the quest group that this completed quest list belongs to. One CompletedQuestList exists per user per quest group. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item CompletedQuestList Completed Quest List Implementation Example describeQuestGroupModels Get a list of Quest Groups Retrieves the list of currently active quest group models. Quest groups serve as categories that organize quests, and a user can only have one quest in progress per group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Quest Group Models Implementation Example getQuestGroupModel Get Quest Group Model Retrieves the specified quest group model including its challenge period event settings and the list of quest models it contains. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestGroupModel Quest Group Model Implementation Example describeQuestModels Get a list of Quest Models Retrieves the list of currently active quest models within the specified quest group. These models define the quest content, rewards, and conditions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Quest Models Implementation Example getQuestModel Get Quest Model Retrieves the specified quest model including its content definitions, reward settings, consume actions, and prerequisite quest conditions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questName string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestModel Implementation Example exportMaster Export Quest Model Master in a master data format that can be activated Exports the currently registered quest group model masters and quest model masters in an activatable master data format. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentQuestMaster master data that can be activated Implementation Example getCurrentQuestMaster Get currently active Quest Model master data Retrieves the currently active quest model master data including quest group models and quest models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentQuestMaster Currently active Quest Model master data Implementation Example preUpdateCurrentQuestMaster Update currently active Quest Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentQuestMaster Update currently active Quest Model master data Updates the currently active quest model master data. Supports both direct update mode and pre-upload mode for handling large master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentQuestMaster Updated master data of the currently active Quest Models Implementation Example updateCurrentQuestMasterFromGitHub Update currently active Quest Model master data from GitHub Updates the currently active quest model master data by checking out master data from a GitHub repository using the specified checkout settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentQuestMaster Updated master data of the currently active Quest Models Implementation Example describeQuestGroupModelMasters Get a list of Quest Group Model Masters Retrieves a paginated list of quest group model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Quest Group name prefix 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 List of Quest Group Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createQuestGroupModelMaster Create a new Quest Group Model Master Creates a new quest group model master with the specified name, description, metadata, and optional challenge period event settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item QuestGroupModelMaster Quest Group Model Master created Implementation Example getQuestGroupModelMaster Get Quest Group Model Master Retrieves the specified quest group model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestGroupModelMaster Quest Group Model Master Implementation Example updateQuestGroupModelMaster Update Quest Group Model Master Updates the specified quest group model master’s description, metadata, and challenge period event settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item QuestGroupModelMaster Quest Group Model Master updated Implementation Example deleteQuestGroupModelMaster Delete Quest Group Model Master Deletes the specified quest group model master. This also removes all quest model masters within the group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestGroupModelMaster Quest Group Model Master deleted Implementation Example describeQuestModelMasters Get a list of Quest Model Masters Retrieves a paginated list of quest model masters within the specified quest group. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Quest Model name prefix 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 List of Quest Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createQuestModelMaster Create a new Quest Model Master Creates a new quest model master with content definitions, reward settings, consume actions, verify actions, failed acquire actions, and prerequisite quest names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. contents List  1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. Result Type Description item QuestModelMaster Quest Model Master created Implementation Example getQuestModelMaster Get Quest Model Master Retrieves the specified quest model master including its content definitions, reward settings, and prerequisite conditions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questName string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestModelMaster Quest Model Master Implementation Example updateQuestModelMaster Update Quest Model Master Updates the specified quest model master’s content definitions, reward settings, consume actions, verify actions, failed acquire actions, and prerequisite quest names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questName string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. contents List  1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. Result Type Description item QuestModelMaster Quest Model Master updated Implementation Example deleteQuestModelMaster Delete Quest Model master Deletes the specified quest model master from the quest group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questGroupName string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). questName string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item QuestModelMaster Quest Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Quest SDK for various programming languages\n","title":"GS2-Quest SDK API Reference","url":"/api_reference/quest/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing ranking operations. lastCalculatedAts List [] 0 ~ 1000 items Last Calculated At List A list of timestamps recording when each category’s global ranking was last calculated. One entry per category is maintained; when a recalculation completes, the corresponding entry is updated (or a new entry is appended for newly created categories). logSetting LogSetting Log Setting Configuration for outputting ranking-related operation logs to GS2-Log. When configured, actions such as score registration, ranking retrieval, and subscription changes are recorded for analysis and auditing. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Subscribe Subscription Holds the subscription state for scope ranking, tracking which users’ scores a player is following. In scope ranking mode, each player sees a personalized leaderboard based on the users they subscribe to. The targetUserIds list represents users the player wants to track, while subscribedUserIds represents the confirmed (mutual or accepted) subscriptions. Maximum 10,000 subscriptions per user per category. Details  subscribeId string * ~ 1024 chars Subscription A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID targetUserIds List [] 0 ~ 10000 items Target User IDs The list of user IDs whose scores the player wants to track in the scope ranking. Adding a user ID to this list includes their scores in the player’s personalized leaderboard. Maximum 10,000 entries. subscribedUserIds List [] 0 ~ 10000 items Subscribed User IDs The list of user IDs who have subscribed to (are following) this player’s scores. Represents the reverse direction of the subscription relationship — these users will see this player’s scores in their scope rankings. Maximum 10,000 entries. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Score Score Holds the registered scores for each game player per category. Each score entry is identified by a unique ID and associated with a category and scorer user. In sum mode, new scores are added to the existing total via the AddScore operation rather than creating separate entries. Scores outside the category’s minimum/maximum range are rejected at registration. Details  scoreId string * ~ 1024 chars Score A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID uniqueId string  UUID ~ 36 chars Unique ID A UUID that uniquely identifies this score entry. Automatically generated on creation. Used to distinguish multiple score entries from the same user in the same category when uniqueByUserId is disabled. scorerUserId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value registered by the player. Must be within the category’s configured minimum/maximum range. In sum mode, this value can be incremented via the AddScore operation. metadata string ~ 512 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Ranking Ranking Represents a single entry in a ranking leaderboard, containing the user’s rank, score, and associated metadata. There are two types: global ranking (all players compete on a shared board with batch calculation) and scope ranking (per-user boards based on subscribed players with real-time reflection). Rankings are sorted by the category’s configured order direction, and entries with the same score share the same rank while maintaining distinct indices. Details  rank long  1 ~ 9223372036854775805 Rank The ranking position of this entry, starting from 1. Entries with the same score share the same rank value. For example, if two users tie for 1st place, both have rank 1 and the next entry has rank 3. index long  0 ~ 9223372036854775805 Index A zero-based sequential index within the ranking list. Unlike rank, the index is always unique and sequential even when multiple entries share the same score. Used for pagination and range-based queries. categoryName string  ~ 128 chars Category Model name userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. metadata string ~ 512 chars Metadata Arbitrary metadata associated with this ranking entry. Inherited from the score registration and returned alongside ranking results. Maximum 512 characters. createdAt long  Creation Timestamp Unix time, milliseconds * Automatically configured on the server SubscribeUser Subscribe User Represents an individual subscription relationship within a scope ranking category. Each entry indicates that the parent user is subscribed to (following) the target user’s scores in the specified category. Details  subscribeUserId string * ~ 1024 chars Subscription Target A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server categoryName string  ~ 128 chars Category Model name userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Target User ID The user ID of the player being subscribed to. This user’s scores will appear in the subscribing user’s scope ranking for the specified category. CategoryModel Category Model Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation. Details  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. Scope Aggregation Scope Defines an additional time-windowed aggregation scope for Global Ranking mode. Normally, global ranking is calculated for all registered scores regardless of when they were submitted. By adding scopes, you can create separate rankings that only consider scores registered within a specified number of days, enabling daily, weekly, or monthly leaderboards alongside the all-time ranking. Details  name string  ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. targetDays long  1 ~ 365 Target Days The number of days to include in the aggregation window. Only scores registered within this number of days from the current time are considered for the scoped ranking. Range: 1-365 days. GlobalRankingSetting Global Ranking Setting Global is a ranking where all players see the same results. The ranking interval can be set from 15 minutes to 24 hours. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation. Details  uniqueByUserId bool true Unique By User ID When enabled, only one score per user ID is kept in the ranking. If a user submits a new score, it replaces the previous one (keeping the better score based on the sort direction). When disabled, multiple score entries from the same user are allowed, enabling sum-mode or multi-entry competition. calculateIntervalMinutes int  15 ~ 1440 Calculate Interval Minutes The interval in minutes between successive ranking recalculations. The system periodically recalculates the global ranking based on all registered scores at this interval. Range: 15 to 1440 minutes (15 minutes to 24 hours). calculateFixedTiming FixedTiming Calculate Fixed Timing Specifies a fixed time of day (UTC) at which ranking recalculation starts. If not set, recalculation occurs at regular intervals from an unspecified base time. Setting this ensures recalculations happen at a predictable, consistent time each day. additionalScopes List 0 ~ 10 items Additional Scopes A list of additional time-windowed aggregation scopes. Each scope defines a separate ranking that only considers scores registered within a specified number of days. This enables creating daily, weekly, or monthly leaderboards alongside the all-time global ranking. Maximum 10 scopes. ignoreUserIds List 0 ~ 10000 items Ignore User IDs A list of user IDs whose scores should be excluded from ranking calculation. Useful for filtering out test accounts, administrator accounts, or known cheaters from the leaderboard. Maximum 10,000 entries. generation string ~ 256 chars Generation An arbitrary string representing the current ranking generation. Changing this value effectively resets all registered scores, as scores from a previous generation are no longer included in ranking calculations. Useful for implementing seasonal resets or periodic ranking resets. Maximum 256 characters. FixedTiming Fixed Timing Specifies the fixed time of day at which global ranking calculations start. Without this setting, ranking calculation occurs at regular intervals from an unspecified base time. By specifying a fixed hour and minute, you can ensure that ranking recalculation always begins at a predictable time (in UTC), such as midnight or a specific hour. Details  hour int 0 ~ 23 Hour The hour (UTC) at which ranking calculation starts. Specified as an integer from 0 to 23. minute int 0 ~ 59 Minute The minute at which ranking calculation starts within the specified hour. Specified as an integer from 0 to 59. CalculatedAt Calculated At Records the timestamp of the last ranking calculation for a specific category. The namespace maintains a list of these entries, one per category, which is updated each time a global ranking recalculation completes. Details  categoryName string  ~ 128 chars Category Name The name of the category model whose last calculation time is being tracked. Matches the name field of a CategoryModel defined in the same namespace. calculatedAt long  Calculated At The timestamp when the ranking calculation last completed for this category. Expressed as Unix time in milliseconds. Automatically set by the server when a ranking recalculation finishes. CurrentRankingMaster Currently active Ranking Model master data This master data defines the Ranking Models currently active within the namespace. Master data describing the currently valid ranking model definitions within the namespace GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Ranking Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data CategoryModelMaster Category Model Master Category Model Master is data used to edit and manage Category Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Category Model actually referenced by the game. Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scoped as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation. Details  categoryModelId string * ~ 1024 chars Category Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing ranking operations. logSetting LogSetting Log Setting Configuration for outputting ranking-related operation logs to GS2-Log. When configured, actions such as score registration, ranking retrieval, and subscription changes are recorded for analysis and auditing. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing ranking operations. logSetting LogSetting Log Setting Configuration for outputting ranking-related operation logs to GS2-Log. When configured, actions such as score registration, ranking retrieval, and subscription changes are recorded for analysis and auditing. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example subscribe Subscribe to target users Subscribes to the specified target user’s ranking in the specified category. The target user’s scores will be included in the requesting user’s scoped ranking. Cannot subscribe to yourself. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars Target User ID Result Type Description item SubscribeUser Subscribed User Information Implementation Example subscribeByUserId Subscribe to the target user by specifying a user ID Subscribes to the specified target user’s ranking in the specified category on behalf of the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Target User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Subscribed User Information Implementation Example describeScores Get a list of Scores Retrieves a paginated list of scores registered by the specified scorer in the specified category. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name accessToken string  ~ 128 chars Access token scorerUserId string  ~ 128 chars User ID 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 List of Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeScoresByUserId Get a list of Scores by specifying a user ID Retrieves a paginated list of scores registered by the specified scorer in the specified category for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name userId string  ~ 128 chars User ID scorerUserId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example getScore Get Score Retrieves a specific score record by specifying the category, scorer user ID, and unique ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name accessToken string  ~ 128 chars Access token scorerUserId string  ~ 128 chars User ID uniqueId string “0” ~ 36 chars Score Unique ID Result Type Description item Score Score Implementation Example getScoreByUserId Get score by specifying a user ID Retrieves a specific score record for the specified user by specifying the category, scorer user ID, and unique ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID scorerUserId string  ~ 128 chars User ID uniqueId string “0” ~ 36 chars Score Unique ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Score Score Implementation Example describeRankings Get Ranking Retrieves a paginated ranking list for the specified category. Supports both global rankings and scoped rankings. Can specify a start index to begin retrieval from a specific rank position. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string ~ 128 chars Access token additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. startIndex long 0 ~ 9223372036854775805 Index to start retrieving rankings pageToken string ~ 4096 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 List of Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeRankingssByUserId Get ranking by specifying a user ID Retrieves a paginated ranking list for the specified category and user. Supports both global rankings and scoped rankings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string ~ 128 chars User ID additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. startIndex long 0 ~ 9223372036854775805 Index to start retrieving rankings pageToken string ~ 4096 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data items to retrieve timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeNearRankings Get ranking near the specified score This API is only available for global ranking Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. Result Type Description items List List of Ranking Scores Implementation Example getRanking Get Ranking Retrieves the ranking information for a specific scorer’s score, including rank position. Also returns nearby rankings around the specified score. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token scorerUserId string  ~ 128 chars User ID of the user who earned the score uniqueId string “0” ~ 36 chars Score Unique ID additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. Result Type Description item Ranking Ranking Implementation Example getRankingByUserId Get ranking by specifying a user ID Retrieves the ranking information for a specific scorer’s score for the specified user, including rank position. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID from which the ranking is obtained (used to determine the duration of the GS2-Schedule). scorerUserId string  ~ 128 chars User ID of the user who earned the score uniqueId string “0” ~ 36 chars Score Unique ID additionalScopeName string ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Ranking Ranking Implementation Example putScore Register score Registers a score for the requesting user in the specified ranking category. The score is routed to either global or scoped ranking processing based on the category type. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. metadata string ~ 512 chars Metadata Arbitrary metadata associated with this ranking entry. Inherited from the score registration and returned alongside ranking results. Maximum 512 characters. Result Type Description item Score Registered Scores Implementation Example putScoreByUserId Register scores by specifying a user ID Registers a score for the specified user in the specified ranking category. The score is routed to either global or scoped ranking processing based on the category type. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value for this ranking entry. In sum mode, this is the accumulated total of all registered scores. The value used for ranking sort order depends on the category’s orderDirection setting. metadata string ~ 512 chars Metadata Arbitrary metadata associated with this ranking entry. Inherited from the score registration and returned alongside ranking results. Maximum 512 characters. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Score Registered Scores Implementation Example calcRanking Forced execution of the ranking calculation process Triggers an immediate ranking recalculation for the specified category, regardless of the scheduled calculation timing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name additionalScopeName string ~ 128 chars Additional scope Result Type Description processing bool the aggregation process ongoing with asynchronous processing Implementation Example getSubscribe Get Subscribed User Information Retrieves the subscription information for a specific target user in the specified ranking category. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars User ID Result Type Description item SubscribeUser Subscribed User Information Implementation Example getSubscribeByUserId Get Subscribed User Information by specifying a user ID Retrieves the subscription information for a specific target user in the specified ranking category for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Subscribed User Information Implementation Example unsubscribe Unsubscribe the target user Removes the subscription to the specified target user’s ranking in the specified category. The target user’s scores will no longer appear in the requesting user’s scoped ranking. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars Target User ID Result Type Description item SubscribeUser Unsubscribed Subscribed User Information Implementation Example unsubscribeByUserId Unsubscribe the target user by specifying a user ID Removes the subscription to the specified target user’s ranking in the specified category on behalf of the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Name userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Target User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Unsubscribed Subscribed User Information Implementation Example describeSubscribesByCategoryName Obtaining a list of user IDs of subscribed users Retrieves the list of users that the requesting user is subscribed to for the specified ranking category. Subscribed users’ scores are included in scoped rankings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name accessToken string  ~ 128 chars Access token Result Type Description items List List of Subscribed User Information Implementation Example describeSubscribesByCategoryNameAndUserId Obtaining a list of users to which the user is subscribed by specifying the user ID Retrieves the list of users that the specified user is subscribed to for the specified ranking category. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Subscribed User Information Implementation Example describeCategoryModels Get a list of Category Models Retrieves the list of currently active category models. Category models define ranking categories with their scoring rules, calculation settings, and scope configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Category Models Implementation Example getCategoryModel Get Category Model Retrieves the specified category model including its scoring range, sort order, scope type, global ranking settings, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModel Category Model Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently registered category model masters in an activatable master data format. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRankingMaster master data that can be activated Implementation Example getCurrentRankingMaster Get currently active Ranking Model master data Retrieves the currently active ranking model master data including category model definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRankingMaster Currently active Ranking Model master data Implementation Example preUpdateCurrentRankingMaster Update currently active Ranking Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentRankingMaster Update currently active Ranking Model master data Updates the currently active ranking model master data. Supports both direct update mode and pre-upload mode for handling large master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example updateCurrentRankingMasterFromGitHub Update currently active Ranking Model master data from GitHub Updates the currently active ranking model master data by checking out master data from a GitHub repository using the specified checkout settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example describeCategoryModelMasters Get a list of Category Model Masters Retrieves a paginated list of category model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Category Model name prefix 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 List of Category Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createCategoryModelMaster Create a new Category Model Master Creates a new category model master with scoring range, sort order, scope type, global ranking settings, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. Result Type Description item CategoryModelMaster Category Model Master created Implementation Example getCategoryModelMaster Get Category Model Master Retrieves the specified category model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModelMaster Category Model Master Implementation Example updateCategoryModelMaster Update Category Model Master Updates the specified category model master’s scoring range, sort order, scope type, global ranking settings, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. Result Type Description item CategoryModelMaster Category Model Master updated Implementation Example deleteCategoryModelMaster Delete Category Model Master Deletes the specified category model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). categoryName string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CategoryModelMaster Category Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Ranking SDK for various programming languages\n","title":"GS2-Ranking SDK API Reference","url":"/api_reference/ranking/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used to grant ranking rewards. Supports auto-run to automatically execute transactions and atomic commit for all-or-nothing guarantee. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking score submissions and ranking reward distributions. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” GlobalRankingScore Global Ranking Score Stores a user’s submitted score for a global ranking in a specific season. When the sum mode is enabled, multiple submitted scores are accumulated. Details  globalRankingScoreId string * ~ 1024 chars Global Ranking Score A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. metadata string ~ 512 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision GlobalRankingReceivedReward Global Ranking Reward Received History It is possible to set rewards for global ranking positions. To set rewards, set the ranking threshold and reward details. Details  globalRankingReceivedRewardId string * ~ 1024 chars Global Ranking Received Reward A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision GlobalRankingData Global Ranking Represents a ranked entry in the global ranking for a specific season. Contains the user’s score, 0-based index (sorted position), and 1-based rank (which accounts for ties). The rank is calculated as index + 1. Details  globalRankingDataId string * ~ 1024 chars Global Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. userId string  ~ 128 chars User ID index int 0 ~ 2147483646 Index The 0-based unique sorted position of this entry in the ranking. Unlike rank, index is always unique even when scores are tied. Used for index-based reward calculation. rank int 0 ~ 2147483646 Rank The 1-based ranking position. Players with the same score share the same rank. Calculated as index + 1. Used for rank-based reward calculation. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. invertUpdatedAt long  0 ~ 9223372036854775805 Inverted value of updatedAt (used for sorting) createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ClusterRankingScore Cluster Ranking Score Stores a user’s submitted score for a cluster ranking in a specific season and cluster. The user’s cluster membership is verified based on the cluster type setting before the score is accepted. Details  clusterRankingScoreId string * ~ 1024 chars Cluster Ranking Score A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. metadata string ~ 512 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ClusterRankingReceivedReward Cluster Ranking Reward Received History You can set rewards according to the cluster ranking. To set rewards, set the ranking threshold and reward details. Details  clusterRankingReceivedRewardId string * ~ 1024 chars Cluster Ranking Received Reward A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID receivedAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ClusterRankingData Cluster Ranking Represents a ranked entry in a cluster ranking for a specific season and cluster. Contains the user’s score, 0-based index, and 1-based rank within the cluster. Details  clusterRankingDataId string * ~ 1024 chars Cluster Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID index int 0 ~ 2147483646 Index The 0-based unique sorted position within the cluster ranking. Always unique even when scores are tied. rank int 0 ~ 2147483646 Rank The 1-based ranking position within the cluster. Players with the same score share the same rank. Calculated as index + 1. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. invertUpdatedAt long  0 ~ 9223372036854775805 Inverted value of updatedAt (used for sorting) createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Subscribe Subscribe By subscribing to other players, you can have their latest scores reflected on your own leaderboard. Details  subscribeId string * ~ 1024 chars Subscribe Score A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserIds List [] 0 ~ 1000 items Subscribe Target User IDs List of user IDs that this user has subscribed to. Their scores will appear in this user’s subscribe ranking. Maximum 1000 users can be subscribed to. Duplicate subscriptions are prevented. fromUserIds List [] 0 ~ 1000 items Subscribe From User IDs List of user IDs who have subscribed to this user. This is the reverse relationship of targetUserIds, tracking which users are following this user’s scores. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscribeRankingScore Subscribe Ranking Score Stores a user’s submitted score for a subscribe ranking in a specific season. This score is visible to users who have subscribed to this user, forming their personalized friend ranking. Details  subscribeRankingScoreId string * ~ 1024 chars Subscribe Ranking Score A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscribeRankingData Subscribe Ranking Represents a ranked entry in a user’s personalized subscribe ranking for a specific season. Contains scores from subscribed users, ranked among the user’s friend list. Each entry includes the scorer’s user ID to identify who achieved the score. Details  subscribeRankingDataId string * ~ 1024 chars Subscribe Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. userId string  ~ 128 chars User ID index int 0 ~ 2147483646 Index The 0-based unique sorted position within the subscribe ranking. rank int 0 ~ 2147483646 Rank The 1-based ranking position within the subscribe ranking. Calculated as index + 1. scorerUserId string  ~ 128 chars Scorer User ID The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend’s score this entry represents. score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. invertUpdatedAt long  0 ~ 9223372036854775805 Inverted value of updatedAt (used for sorting) createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscribeUser Subscribed User Information Represents a subscription relationship between two users for the subscribe ranking. Details  rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Subscribe Target User ID The user ID of the player being subscribed to. This player’s scores will be included in the subscriber’s personalized ranking. GlobalRankingModel Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. Details  globalRankingModelId string * ~ 1024 chars Global Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index ClusterRankingModel Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. Details  clusterRankingModelId string * ~ 1024 chars Cluster Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index SubscribeRankingModel Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking. Details  subscribeRankingModelId string * ~ 1024 chars Subscribe Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. RankingReward Ranking Reward Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards. Details  thresholdRank int  1 ~ 1001 Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). metadata string ~ 1024 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. acquireActions List [] 0 ~ 100 items List of Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value CurrentRankingMaster Currently active Ranking Model master data This master data defines the Ranking Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Ranking2 Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data GlobalRankingModelMaster Global Ranking Model Master Global Ranking Model Master is data used to edit and manage global ranking model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as global ranking model actually referenced by the game. The global ranking model is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. Details  globalRankingModelId string * ~ 1024 chars Global Ranking Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ClusterRankingModelMaster Cluster Ranking Model Master Cluster Ranking Model Master is data used to edit and manage cluster ranking model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as cluster ranking model actually referenced by the game. The cluster ranking model is a model for realizing rankings targeting players in guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. Details  clusterRankingModelId string * ~ 1024 chars Cluster Ranking Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SubscribeRankingModelMaster Subscribe Ranking Model Master Subscribe Ranking Model Master is data used to edit and manage subscribe ranking model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as subscribe ranking model actually referenced by the game. The Subscription Ranking Model that aggregates scores of other players that the user has subscribed to and creates a ranking. Details  subscribeRankingModelId string * ~ 1024 chars Subscribe Ranking Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used to grant ranking rewards. Supports auto-run to automatically execute transactions and atomic commit for all-or-nothing guarantee. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking score submissions and ranking reward distributions. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used to grant ranking rewards. Supports auto-run to automatically execute transactions and atomic commit for all-or-nothing guarantee. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking score submissions and ranking reward distributions. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeGlobalRankingScores Get a list of Global Ranking Scores Retrieves a paginated list of global ranking scores registered by the requesting user. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string ~ 128 chars Global Ranking Model name Global Ranking 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 List of Global Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeGlobalRankingScoresByUserId Get a list of Global Ranking Scores by specifying a user ID Retrieves a paginated list of global ranking scores registered by the specified user. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string ~ 128 chars Global Ranking Model name Global Ranking 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Global Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example putGlobalRankingScore Register Global Ranking Score Registers a score for the specified global ranking. The score must be within the range defined by the ranking model. If the entry period event is configured, scores can only be registered during the active period. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. metadata string ~ 512 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. Result Type Description item GlobalRankingScore Registered Global Ranking Score Implementation Example putGlobalRankingScoreByUserId Register Global Ranking Score specifying User ID Registers a score for the specified global ranking on behalf of the specified user. The score must be within the range defined by the ranking model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. metadata string ~ 512 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingScore Registered Global Ranking Score Implementation Example getGlobalRankingScore Get Global Ranking Score Retrieves the global ranking score registered by the requesting user for the specified ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item GlobalRankingScore Global Ranking Score Implementation Example getGlobalRankingScoreByUserId Get Global Ranking Score specifying User ID Retrieves the global ranking score registered by the specified user for the specified ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingScore Global Ranking Score Implementation Example deleteGlobalRankingScoreByUserId Delete Global Ranking Score specifying User ID Deletes the global ranking score registered by the specified user for the specified ranking and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingScore Global Ranking Score deleted Implementation Example verifyGlobalRankingScore Verify the score of the global ranking Verifies the global ranking score against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item GlobalRankingScore Global Ranking Score Implementation Example verifyGlobalRankingScoreByUserId Verify the score of the global ranking specifying User ID Verifies the global ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingScore Global Ranking Score Implementation Example describeGlobalRankingReceivedRewards Get a list of Global Ranking Rewards Received Retrieves a paginated list of global ranking reward receipt history for the requesting user. Can filter by ranking name and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 List of Global Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeGlobalRankingReceivedRewardsByUserId Get a list of Global Ranking Rewards Received by specifying a user ID Retrieves a paginated list of global ranking reward receipt history for the specified user. Can filter by ranking name and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Global Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGlobalRankingReceivedReward Record global ranking reward receipt history Records a reward receipt history for the specified global ranking. This must be done before actually receiving the reward. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item GlobalRankingReceivedReward Global Ranking Reward Received History Implementation Example createGlobalRankingReceivedRewardByUserId Record global ranking reward receipt history specifying User ID Records a reward receipt history for the specified global ranking on behalf of the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingReceivedReward Global Ranking Reward Received History Implementation Example receiveGlobalRankingReceivedReward Receive Global Ranking Reward Receives the ranking reward for the specified global ranking and season. The reward is determined by the user’s ranking position and the ranking model’s reward configuration. A transaction is issued to grant the reward items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item GlobalRankingModel Global Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example receiveGlobalRankingReceivedRewardByUserId Receive Global Ranking Reward specifying User ID Receives the ranking reward for the specified global ranking and season on behalf of the specified user. A transaction is issued to grant the reward items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingModel Global Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example getGlobalRankingReceivedReward Get Global Ranking Reward Received History Retrieves the reward receipt history for the specified global ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item GlobalRankingReceivedReward Global Ranking Reward Received History Implementation Example getGlobalRankingReceivedRewardByUserId Get Global Ranking Reward Received History specifying User ID Retrieves the reward receipt history for the specified global ranking for the specified user. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingReceivedReward Global Ranking Reward Received History Implementation Example deleteGlobalRankingReceivedRewardByUserId Delete Global Ranking Reward Received History specifying User ID Deletes the global ranking reward receipt history for the specified user, ranking, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. Increments with each new ranking period. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingReceivedReward Global Ranking Reward Received History deleted Implementation Example describeGlobalRankings Get a list of Global Rankings Retrieves a paginated list of global ranking data for the specified ranking. Ranking data includes rank, score, and user information. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 List of Global Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeGlobalRankingsByUserId Get a list of Global Rankings by specifying a user ID Retrieves a paginated list of global ranking data for the specified ranking on behalf of the specified user. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Global Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getGlobalRanking Get Global Ranking Retrieves the ranking position and score of the requesting user for the specified global ranking. The ranking data is calculated from registered scores. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item GlobalRankingData Global Ranking Implementation Example getGlobalRankingByUserId Get Global Ranking by specifying the user ID Retrieves the ranking position and score of the specified user for the specified global ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item GlobalRankingData Global Ranking Implementation Example describeClusterRankingScores Get a list of Cluster Ranking Scores Retrieves a paginated list of cluster ranking scores registered by the requesting user. Can filter by ranking name, cluster name, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long 0 ~ 9223372036854775805 Season 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 List of Cluster Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeClusterRankingScoresByUserId Get a list of Cluster Ranking Scores by specifying a user ID Retrieves a paginated list of cluster ranking scores registered by the specified user. Can filter by ranking name, cluster name, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Cluster Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example putClusterRankingScore Register Cluster Ranking Score Registers a score for the specified cluster ranking. The user must belong to the specified cluster (guild or matchmaking gathering). The score must be within the range defined by the ranking model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. accessToken string  ~ 128 chars Access token score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. metadata string ~ 512 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. Result Type Description item ClusterRankingScore Registered Cluster Ranking Score Implementation Example putClusterRankingScoreByUserId Register Cluster Ranking Score specifying User ID Registers a score for the specified cluster ranking on behalf of the specified user. The user must belong to the specified cluster. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. metadata string ~ 512 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingScore Registered Cluster Ranking Score Implementation Example getClusterRankingScore Get Cluster Ranking Score Retrieves the cluster ranking score registered by the requesting user for the specified ranking and cluster. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item ClusterRankingScore Cluster Ranking Score Implementation Example getClusterRankingScoreByUserId Get Cluster Ranking Score specifying User ID Retrieves the cluster ranking score registered by the specified user for the specified ranking and cluster. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingScore Cluster Ranking Score Implementation Example deleteClusterRankingScoreByUserId Delete Cluster Ranking Score specifying User ID Deletes the cluster ranking score registered by the specified user for the specified ranking, cluster, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingScore Cluster Ranking Score deleted Implementation Example verifyClusterRankingScore Verify the score of the cluster ranking Verifies the cluster ranking score against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item ClusterRankingScore Cluster Ranking Score Implementation Example verifyClusterRankingScoreByUserId Verify the score of the cluster ranking specifying User ID Verifies the cluster ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingScore Cluster Ranking Score Implementation Example describeClusterRankingReceivedRewards Get a list of Cluster Ranking Rewards Received Retrieves a paginated list of cluster ranking reward receipt history for the requesting user. Can filter by ranking name, cluster name, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season 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 List of Cluster Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeClusterRankingReceivedRewardsByUserId Get a list of Cluster Ranking Rewards Received by specifying a User ID Retrieves a paginated list of cluster ranking reward receipt history for the specified user. Can filter by ranking name, cluster name, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Cluster Ranking Rewards Received nextPageToken string Page token to retrieve the rest of the listing Implementation Example createClusterRankingReceivedReward Record Cluster Ranking Reward Received History Records a reward receipt history for the specified cluster ranking and cluster. This must be done before actually receiving the reward. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item ClusterRankingReceivedReward Cluster Ranking Reward Received History Implementation Example createClusterRankingReceivedRewardByUserId Record Cluster Ranking Reward Received History by specifying a user ID Records a reward receipt history for the specified cluster ranking and cluster on behalf of the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingReceivedReward Cluster Ranking Reward Received History Implementation Example receiveClusterRankingReceivedReward Receive Cluster Ranking Reward Receives the ranking reward for the specified cluster ranking, cluster, and season. The reward is determined by the user’s ranking position and the ranking model’s reward configuration. A transaction is issued to grant the reward items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item ClusterRankingModel Cluster Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example receiveClusterRankingReceivedRewardByUserId Receive Cluster Ranking Reward specifying User ID Receives the ranking reward for the specified cluster ranking, cluster, and season on behalf of the specified user. A transaction is issued to grant the reward items. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. season long 0 ~ 9223372036854775805 Season config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingModel Cluster Ranking Model acquireActions List List of Acquire Actions to be performed when rewards are received transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the exchange process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example getClusterRankingReceivedReward Get Cluster Ranking Reward Received History Retrieves the reward receipt history for the specified cluster ranking and cluster. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item ClusterRankingReceivedReward Cluster Ranking Reward Received History Implementation Example getClusterRankingReceivedRewardByUserId Get Cluster Ranking Reward Received History specifying User ID Retrieves the reward receipt history for the specified cluster ranking and cluster for the specified user. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingReceivedReward Cluster Ranking Reward Received History Implementation Example deleteClusterRankingReceivedRewardByUserId Delete Cluster Ranking Reward Received History specifying User ID Deletes the cluster ranking reward receipt history for the specified user, ranking, cluster, and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. userId string  ~ 128 chars User ID season long  0 ~ 9223372036854775805 Season The season number corresponding to the GS2-Schedule event repeat count. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingReceivedReward Cluster Ranking Reward Received History deleted Implementation Example describeClusterRankings Get a list of Cluster Rankings Retrieves a paginated list of cluster ranking data for the specified ranking and cluster. Ranking data includes rank, score, and user information. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long 0 ~ 9223372036854775805 Season 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 List of Cluster Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeClusterRankingsByUserId Get a list of Cluster Rankings by specifying a user ID Retrieves a paginated list of cluster ranking data for the specified ranking and cluster on behalf of the specified user. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Cluster Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getClusterRanking Get Cluster Ranking Retrieves the ranking position and score of the requesting user for the specified cluster ranking. The ranking data is calculated from registered scores within the cluster. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item ClusterRankingData Cluster Ranking Implementation Example getClusterRankingByUserId Get Cluster Ranking by specifying the user ID Retrieves the ranking position and score of the specified user for the specified cluster ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or group) that this season belongs to. userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item ClusterRankingData Cluster Ranking Implementation Example describeSubscribes Get a list of Subscribed User Information Retrieves a paginated list of users that the requesting user has subscribed to for subscribe rankings. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking 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 List of Subscribed User Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSubscribesByUserId Get a list of Subscribed User Information by specifying a user ID Retrieves a paginated list of users that the specified user has subscribed to for subscribe rankings. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Subscribed User Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example addSubscribe Register Subscribe Target User ID Subscribes to the specified target user for the specified subscribe ranking. The target user’s scores will be included in the requesting user’s subscribe ranking. When a subscription is added, existing scores of the target user are synced to the subscriber’s ranking data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars Subscribe Target User ID Result Type Description item SubscribeUser Registered Subscribe Target User ID Implementation Example addSubscribeByUserId Register Subscribe Target User ID specifying User ID Subscribes to the specified target user for the specified subscribe ranking on behalf of the specified user. Existing scores are synced to the subscriber’s ranking data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Subscribe Target User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Registered Subscribe Target User ID Implementation Example describeSubscribeRankingScores Get a list of Subscribe Ranking Scores Retrieves a paginated list of subscribe ranking scores registered by the requesting user. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string ~ 128 chars Subscribe Ranking Model name Subscribe Ranking 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 List of Subscribe Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSubscribeRankingScoresByUserId Get a list of Subscribe Ranking Scores by specifying a User ID Retrieves a paginated list of subscribe ranking scores registered by the specified user. Can filter by ranking name. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string ~ 128 chars Subscribe Ranking Model name Subscribe Ranking 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Subscribe Ranking Scores nextPageToken string Page token to retrieve the rest of the listing Implementation Example putSubscribeRankingScore Register Subscribe Ranking Score Registers a score for the specified subscribe ranking. The score is propagated to all subscribers’ ranking data. The score must be within the range defined by the ranking model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. Result Type Description item SubscribeRankingScore Registered Subscribe Ranking Score Implementation Example putSubscribeRankingScoreByUserId Register Subscribe Ranking Score specifying User ID Registers a score for the specified subscribe ranking on behalf of the specified user. The score is propagated to all subscribers’ ranking data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID score long  0 ~ 9223372036854775805 Score metadata string ~ 512 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. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeRankingScore Registered Subscribe Ranking Score Implementation Example getSubscribeRankingScore Get Subscribe Ranking Score Retrieves the subscribe ranking score registered by the requesting user for the specified ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season Result Type Description item SubscribeRankingScore Subscribe Ranking Score Implementation Example getSubscribeRankingScoreByUserId Get Subscribe Ranking Score specifying User ID Retrieves the subscribe ranking score registered by the specified user for the specified ranking. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeRankingScore Subscribe Ranking Score Implementation Example deleteSubscribeRankingScoreByUserId Delete Subscribe Ranking Score specifying User ID Deletes the subscribe ranking score registered by the specified user for the specified ranking and season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeRankingScore Subscribe Ranking Score deleted Implementation Example verifySubscribeRankingScore Verify the score of the subscribe ranking Verifies the subscribe ranking score against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item SubscribeRankingScore Subscribe Ranking Score Implementation Example verifySubscribeRankingScoreByUserId Verify the score of the subscribe ranking specifying User ID Verifies the subscribe ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeRankingScore Subscribe Ranking Score Implementation Example describeSubscribeRankings Get a list of Subscribe Rankings Retrieves a paginated list of subscribe ranking data for the specified ranking. The ranking only includes scores from users that the requesting user has subscribed to. Can optionally specify a season. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 List of Subscribe Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeSubscribeRankingsByUserId Get a list of Subscribe Rankings by specifying a user ID Retrieves a paginated list of subscribe ranking data for the specified ranking on behalf of the specified user. The ranking only includes scores from users that the specified user has subscribed to. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long 0 ~ 9223372036854775805 Season 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Subscribe Rankings nextPageToken string Page token to retrieve the rest of the listing Implementation Example getSubscribeRanking Get Subscribe Ranking Retrieves the ranking position and score of the requesting user (or a specified scorer) within the subscribe ranking. Can optionally specify a season and scorer user ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token season long 0 ~ 9223372036854775805 Season scorerUserId string ~ 128 chars Scorer User ID The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend’s score this entry represents. Result Type Description item SubscribeRankingData Subscribe Ranking Implementation Example getSubscribeRankingByUserId Get Subscribe Ranking by specifying the user ID Retrieves the ranking position and score of the specified user (or a specified scorer) within the subscribe ranking. Can optionally specify a season and scorer user ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID season long 0 ~ 9223372036854775805 Season scorerUserId string ~ 128 chars Scorer User ID The user ID of the player who achieved this score. In a subscribe ranking, entries come from subscribed users, so this field identifies which friend’s score this entry represents. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeRankingData Subscribe Ranking Implementation Example getSubscribe Get Subscribe Target User ID Retrieves the subscription information for the specified target user in the specified subscribe ranking. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars Subscribe Target User ID Result Type Description item SubscribeUser Subscribed User Information Implementation Example getSubscribeByUserId Get Subscribe Target User ID specifying User ID Retrieves the subscription information for the specified target user in the specified subscribe ranking for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Subscribe Target User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Subscribed User Information Implementation Example deleteSubscribe Delete Subscribe Target User ID Removes the subscription to the specified target user for the specified subscribe ranking. The target user’s scores will no longer appear in the requesting user’s subscribe ranking. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetUserId string  ~ 128 chars Subscribe Target User ID Result Type Description item SubscribeUser Subscribed User Information deleted Implementation Example deleteSubscribeByUserId Delete Subscribe Target User ID specifying User ID Removes the subscription to the specified target user for the specified subscribe ranking on behalf of the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetUserId string  ~ 128 chars Subscribe Target User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SubscribeUser Subscribed User Information deleted Implementation Example describeGlobalRankingModels Get a list of Global Ranking Models Retrieves the list of currently active global ranking models. Global ranking models define ranking configurations including score range, sort order, reward settings, and entry/access period events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Global Ranking Models Implementation Example getGlobalRankingModel Get Global Ranking Model Retrieves the specified global ranking model including its score range, sort order, ranking rewards, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GlobalRankingModel Global Ranking Model Implementation Example describeClusterRankingModels Get a list of Cluster Ranking Models Retrieves the list of currently active cluster ranking models. Cluster ranking models define ranking configurations with cluster type (guild or matchmaking gathering), score range, sort order, reward settings, and entry/access period events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Cluster Ranking Models Implementation Example getClusterRankingModel Get Cluster Ranking Model Retrieves the specified cluster ranking model including its cluster type, score range, sort order, ranking rewards, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ClusterRankingModel Cluster Ranking Model Implementation Example describeSubscribeRankingModels Get a list of Subscribe Ranking Models Retrieves the list of currently active subscribe ranking models. Subscribe ranking models define ranking configurations where users only compete with subscribed friends, including score range, sort order, and entry/access period events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Subscribe Ranking Models Implementation Example getSubscribeRankingModel Get Subscribe Ranking Model Retrieves the specified subscribe ranking model including its score range, sort order, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SubscribeRankingModel Subscribe Ranking Model Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently registered global, cluster, and subscribe ranking model masters in an activatable master data format. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRankingMaster Export Model Master in a master data format that can be activated Implementation Example getCurrentRankingMaster Get currently active Ranking Model master data Retrieves the currently active ranking model master data including global, cluster, and subscribe ranking model definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentRankingMaster Currently active Ranking Model master data Implementation Example preUpdateCurrentRankingMaster Update currently active Ranking Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentRankingMaster Update currently active Ranking Model master data Updates the currently active ranking model master data. Supports both direct update mode and pre-upload mode for handling large master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example updateCurrentRankingMasterFromGitHub Update currently active Ranking Model master data from GitHub Updates the currently active ranking model master data by checking out master data from a GitHub repository using the specified checkout settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example describeGlobalRankingModelMasters Get a list of Global Ranking Model Masters Retrieves a paginated list of global ranking model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by global ranking model name prefix 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 List of Global Ranking Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createGlobalRankingModelMaster Create Global Ranking Model Master Creates a new global ranking model master with score range, sort order, sum mode, ranking rewards, reward calculation index, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item GlobalRankingModelMaster Global Ranking Model Master created Implementation Example getGlobalRankingModelMaster Get Global Ranking Model Master Retrieves the specified global ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GlobalRankingModelMaster Global Ranking Model Master Implementation Example updateGlobalRankingModelMaster Update Global Ranking Model Master Updates the specified global ranking model master’s score range, sort order, sum mode, ranking rewards, reward calculation index, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item GlobalRankingModelMaster Global Ranking Model Master updated Implementation Example deleteGlobalRankingModelMaster Delete Global Ranking Model Master Deletes the specified global ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item GlobalRankingModelMaster Global Ranking Model Master deleted Implementation Example describeClusterRankingModelMasters Get a list of Cluster Ranking Model Masters Retrieves a paginated list of cluster ranking model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by cluster ranking model name prefix 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 List of Cluster Ranking Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createClusterRankingModelMaster Create Cluster Ranking Model Master Creates a new cluster ranking model master with cluster type, score range, sort order, sum mode, ranking rewards, reward calculation index, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item ClusterRankingModelMaster Cluster Ranking Model Master created Implementation Example getClusterRankingModelMaster Get Cluster Ranking Model Master Retrieves the specified cluster ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ClusterRankingModelMaster Cluster Ranking Model Master Implementation Example updateClusterRankingModelMaster Update Cluster Ranking Model Master Updates the specified cluster ranking model master’s cluster type, score range, sort order, sum mode, ranking rewards, reward calculation index, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item ClusterRankingModelMaster Cluster Ranking Model Master updated Implementation Example deleteClusterRankingModelMaster Delete Cluster Ranking Model Master Deletes the specified cluster ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ClusterRankingModelMaster Cluster Ranking Model Master deleted Implementation Example describeSubscribeRankingModelMasters Get a list of Subscribe Ranking Model Masters Retrieves a paginated list of subscribe ranking model masters. Can filter by name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by subscribe ranking model name prefix 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 List of Subscribe Ranking Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSubscribeRankingModelMaster Create Subscribe Ranking Model Master Creates a new subscribe ranking model master with score range, sort order, sum mode, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item SubscribeRankingModelMaster Subscribe Ranking Model Master created Implementation Example getSubscribeRankingModelMaster Get Subscribe Ranking Model Master Retrieves the specified subscribe ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SubscribeRankingModelMaster Subscribe Ranking Model Master Implementation Example updateSubscribeRankingModelMaster Update Subscribe Ranking Model Master Updates the specified subscribe ranking model master’s score range, sort order, sum mode, and entry/access period event configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item SubscribeRankingModelMaster Subscribe Ranking Model Master updated Implementation Example deleteSubscribeRankingModelMaster Delete Subscribe Ranking Model Master Deletes the specified subscribe ranking model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SubscribeRankingModelMaster Subscribe Ranking Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Ranking2 SDK for various programming languages\n","title":"GS2-Ranking2 SDK API Reference","url":"/api_reference/ranking2/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing realtime operations. serverType string (enum) enum {   “relay” }  Server Type The type of game server to provision for real-time communication. Currently supports “relay” mode, which provides a packet relay server that forwards messages between connected game clients. Definition Description “relay” Packet relay serverSpec string (enum) enum {   “realtime1.nano” }  Server Spec The hardware specification tier for the provisioned game server. Determines the compute resources (CPU, memory) allocated to each room’s server instance. Currently supports “realtime1.nano”. Definition Description “realtime1.nano” realtime1.nano createNotification NotificationSetting Create Notification Push Notification Setting triggered when a room finishes provisioning and is ready for connections. Since room creation is asynchronous (IP address, port, and encryption key are assigned after a short delay), this notification informs clients that the room is ready to accept connections. logSetting LogSetting Log Setting Configuration for outputting realtime-related operation logs to GS2-Log. When configured, actions such as room creation, connection events, and message relay activities are recorded for analysis and debugging. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it. Details  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Room Room Represents a dedicated game server instance for handling real-time communication in multiplayer matches. Room creation is asynchronous: after the request, the system provisions a server and assigns an IP address, port, and encryption key once the instance is ready. Clients should wait for the create notification (or poll) before attempting to connect. The encryption key is used to establish a secure communication channel between the game clients and the relay server. Details  roomId string * ~ 1024 chars Room A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ipAddress string ~ 128 chars IP Address The IP address of the provisioned game server. Assigned automatically by the system after the room’s server instance is ready. Not available immediately after room creation. Maximum 128 characters. port int 0 ~ 65535 Port The listening port number of the provisioned game server. Assigned automatically along with the IP address after the server instance is ready. Range: 0-65535. encryptionKey string ~ 256 chars Encryption Key The encryption key for securing communication between game clients and the relay server. Assigned automatically along with the IP address and port after the server instance is ready. Clients must use this key to encrypt/decrypt messages sent through the relay server. Maximum 256 characters. notificationUserIds List [] 0 ~ 1000 items Notification User IDs A list of user IDs that will receive a push notification when the room finishes provisioning and is ready for connections. Typically includes the players who will participate in the real-time session so they can be notified to connect. Maximum 1,000 entries. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing realtime operations. serverType string (enum) enum {   “relay” }  Server Type The type of game server to provision for real-time communication. Currently supports “relay” mode, which provides a packet relay server that forwards messages between connected game clients. Definition Description “relay” Packet relay serverSpec string (enum) enum {   “realtime1.nano” }  Server Spec The hardware specification tier for the provisioned game server. Determines the compute resources (CPU, memory) allocated to each room’s server instance. Currently supports “realtime1.nano”. Definition Description “realtime1.nano” realtime1.nano createNotification NotificationSetting Create Notification Push Notification Setting triggered when a room finishes provisioning and is ready for connections. Since room creation is asynchronous (IP address, port, and encryption key are assigned after a short delay), this notification informs clients that the room is ready to accept connections. logSetting LogSetting Log Setting Configuration for outputting realtime-related operation logs to GS2-Log. When configured, actions such as room creation, connection events, and message relay activities are recorded for analysis and debugging. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing realtime operations. serverType string (enum) enum {   “relay” }  Server Type The type of game server to provision for real-time communication. Currently supports “relay” mode, which provides a packet relay server that forwards messages between connected game clients. Definition Description “relay” Packet relay serverSpec string (enum) enum {   “realtime1.nano” }  Server Spec The hardware specification tier for the provisioned game server. Determines the compute resources (CPU, memory) allocated to each room’s server instance. Currently supports “realtime1.nano”. Definition Description “realtime1.nano” realtime1.nano createNotification NotificationSetting Create Notification Push Notification Setting triggered when a room finishes provisioning and is ready for connections. Since room creation is asynchronous (IP address, port, and encryption key are assigned after a short delay), this notification informs clients that the room is ready to accept connections. logSetting LogSetting Log Setting Configuration for outputting realtime-related operation logs to GS2-Log. When configured, actions such as room creation, connection events, and message relay activities are recorded for analysis and debugging. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example now Get current time Returns the current server timestamp for time synchronization between client and server. The timestamp is returned in Unix time (milliseconds). Details Request  accessToken string ~ 128 chars Access token Result Type Description timestamp long Current time Unix time, milliseconds Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example describeRooms Get a list of Room Information Retrieves a paginated list of rooms that are currently active in the namespace. Each room contains connection information such as IP address, port, and encryption key. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Room Information nextPageToken string Page token to retrieve the rest of the listing Implementation Example wantRoom Request to create a room Room creation is not completed immediately. You can receive a push notification from the server when room creation is complete. If you wish to be notified, specify in notificationUserIds list of user IDs to whom you wish to send push notifications. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). notificationUserIds List [] 0 ~ 1000 items Notification User IDs A list of user IDs that will receive a push notification when the room finishes provisioning and is ready for connections. Typically includes the players who will participate in the real-time session so they can be notified to connect. Maximum 1,000 entries. Result Type Description item Room Room Information Implementation Example getRoom Get Room Information Retrieves detailed information about the specified room, including its IP address, port, and encryption key needed to connect to the game server. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Room Room Information Implementation Example deleteRoom Delete Room Deletes the specified room and releases the associated game server resources. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). roomName string  ~ 128 chars Room name Room-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Room Room Information Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Realtime SDK for various programming languages\n","title":"GS2-Realtime SDK API Reference","url":"/api_reference/realtime/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing schedule operations. logSetting LogSetting Log Setting Configuration for outputting schedule-related operation logs to GS2-Log. When configured, actions such as event queries, trigger activation, and trigger deletion are recorded for analysis and auditing. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Trigger Trigger Defines the starting point for relative event scheduling, enabling per-player event periods. When a trigger is activated for a player, it records the activation time (triggeredAt) and an expiration time (expiresAt). Events configured with “relative” schedule type reference a trigger by name; the event period for that player starts from the trigger’s activation time and ends at its expiration. Triggers can be renewed (resetting createdAt and updating expiresAt) and are automatically cleaned up via TTL after expiration. Details  triggerId string * ~ 1024 chars Trigger A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID triggeredAt long * Current time Triggered At The timestamp when this trigger was activated. Serves as the reference starting point for relative event scheduling. Automatically set to the current time if not explicitly specified. Expressed as Unix time in milliseconds. expiresAt long  Expires At The timestamp when this trigger expires and the relative event period ends. After this time, the trigger is considered expired (IsExpire returns true) and the associated relative event is no longer active for this player. The trigger data is automatically cleaned up via DynamoDB TTL after expiration. Expressed as Unix time in milliseconds. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Event Event Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period. Details  eventId string * ~ 1024 chars GS2-Schedule Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Event name Event-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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. RepeatSetting Repeat Setting Configures a recurring time window within the overall event period. Supports five repeat types: “always” (entire event period), “daily” (specific hours each day), “weekly” (specific day-of-week range with hours), “monthly” (specific day-of-month range with hours), and “custom” (alternating active/inactive day cycles from an anchor date). When beginHour equals endHour for daily/weekly/monthly types, the end time is treated as the same hour on the following day (i.e., a full 24-hour window). Details  repeatType string (enum) enum {   “always”,   “daily”,   “weekly”,   “monthly”,   “custom” } “always” Repeat Type The type of repeat pattern to apply within the event period. Determines which additional fields are required: daily/weekly/monthly require hour settings, weekly requires day-of-week, monthly requires day-of-month, and custom requires anchor timestamp and day counts. Defaults to “always” if not specified. Definition Description “always” Always during the entire event period “daily” Every day during the event period from X:00 to X:00 “weekly” During the event period, every week from the start day to the end day, X:00 to X:00 “monthly” During the event period, every month from the start date to the end date, X:00 to X:00 “custom” Starting from the reference date, active for X days and inactive for Y days during the event period beginDayOfMonth int {repeatType} == “monthly”  1 ~ 31 Begin Day of Month The day of the month when the repeat window starts (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” endDayOfMonth int {repeatType} == “monthly”  1 ~ 31 End Day of Month The day of the month when the repeat window ends (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” beginDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  Begin Day of Week The day of the week when the repeat window starts. The window can span across week boundaries (e.g., Friday to Monday). Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” endDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  End Day of Week The day of the week when the repeat window ends. Combined with beginDayOfWeek to define the weekly active period. Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” beginHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 23 Begin Hour The hour (UTC, 0-23) at which the repeat window starts each cycle. Required for daily, weekly, and monthly repeat types. If beginHour equals endHour, the window spans a full 24 hours (ending at the same hour the next day). * Required if repeatType is “daily”,“weekly”,“monthly” endHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 24 End Hour The hour (UTC, 0-24) at which the repeat window ends each cycle. A value of 24 represents midnight of the following day. Required for daily, weekly, and monthly repeat types. * Required if repeatType is “daily”,“weekly”,“monthly” anchorTimestamp long {repeatType} == “custom”  Anchor Timestamp The reference date from which the custom active/inactive cycle begins. The system calculates which phase (active or inactive) the current time falls into based on elapsed days from this anchor. Only applicable when repeatType is “custom”. Expressed as Unix time in milliseconds. * Required if repeatType is “custom” activeDays int {repeatType} == “custom”  1 ~ 2147483646 Active Days The number of consecutive days the event is active in each custom cycle. After these active days, the event becomes inactive for the number of days specified by inactiveDays, then the cycle repeats. Only applicable when repeatType is “custom”. Minimum 1 day. * Required if repeatType is “custom” inactiveDays int {repeatType} == “custom”  0 ~ 2147483646 Inactive Days The number of consecutive days the event is inactive in each custom cycle. Follows the active days period. Set to 0 for a continuously active event with no gaps. Only applicable when repeatType is “custom”. Minimum 0 days. * Required if repeatType is “custom” RepeatSchedule Repeat Schedule Represents the current state of an event’s repeat cycle at a given point in time. Contains the repeat count (how many times the cycle has occurred), the current active window’s start and end times, the last completed window’s end time, and the next upcoming window’s start time. This information is computed dynamically from the event’s repeat settings and the current time. Details  repeatCount int  0 ~ 2147483646 Repeat Count The number of repeat cycles that have completed up to the current time. Increments each time a repeat window ends. Useful for tracking progress through seasonal or periodic event cycles. currentRepeatStartAt long Current Repeat Start At The start time of the currently active repeat window. Null if the event is not currently in an active repeat window. Expressed as Unix time in milliseconds. currentRepeatEndAt long Current Repeat End At The end time of the currently active repeat window. Null if the event is not currently in an active repeat window. Expressed as Unix time in milliseconds. lastRepeatEndAt long Last Repeat End At The end time of the most recently completed repeat window. Null if no repeat window has ended yet. Expressed as Unix time in milliseconds. nextRepeatStartAt long Next Repeat Start At The start time of the next upcoming repeat window. Null if there are no more upcoming repeat windows within the event period. Expressed as Unix time in milliseconds. CurrentEventMaster Currently active Event master data This master data defines the Events currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Schedule Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data EventMaster Event Master Event Master is data used to edit and manage event within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as event actually referenced by the game. There are two types of event durations: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period. Details  eventId string * ~ 1024 chars Event Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing schedule operations. logSetting LogSetting Log Setting Configuration for outputting schedule-related operation logs to GS2-Log. When configured, actions such as event queries, trigger activation, and trigger deletion are recorded for analysis and auditing. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing schedule operations. logSetting LogSetting Log Setting Configuration for outputting schedule-related operation logs to GS2-Log. When configured, actions such as event queries, trigger activation, and trigger deletion are recorded for analysis and auditing. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeTriggers Get a list of Triggers Retrieves a paginated list of triggers that have been pulled for the requesting user. Triggers are used to activate relative schedule events and have an expiration time (TTL). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Triggers nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeTriggersByUserId Get a list of Triggers by specifying a user ID Retrieves a paginated list of triggers that have been pulled for the specified user. Triggers are used to activate relative schedule events and have an expiration time (TTL). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Triggers nextPageToken string Page token to retrieve the rest of the listing Implementation Example getTrigger Get trigger Retrieves the specified trigger including its name, creation time, and expiration time (TTL). Returns the trigger’s current state for the requesting user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Trigger Trigger Implementation Example getTriggerByUserId Get Trigger by specifying a user ID Retrieves the specified trigger including its name, creation time, and expiration time (TTL) for the specified user. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Trigger Trigger Implementation Example triggerByUserId Execute the Trigger by specifying a user ID Pulls a trigger for the specified user. The trigger strategy determines behavior: ‘renew’ resets with new TTL, ’extend’ extends existing TTL, ‘drop’ ignores if already pulled, ‘repeatCycleEnd’/‘repeatCycleNextStart’/‘absoluteEnd’ aligns expiration with the specified event’s schedule. Pulling a trigger activates associated relative schedule events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID triggerStrategy string (enum) enum {   “renew”,   “extend”,   “drop”,   “repeatCycleEnd”,   “repeatCycleNextStart”,   “absoluteEnd” }  Trigger Execution Policy Definition Description “renew” Redraw with a new period if the trigger has already been pulled “extend” Extend the period if the trigger has already been pulled “drop” Ignore if the trigger has already been pulled “repeatCycleEnd” Trigger to expire at the end of the repeat period of the specified event “repeatCycleNextStart” Trigger to expire at the next repeat start date and time of the specified event “absoluteEnd” Trigger to expire at the end date and time of the specified event ttl int {triggerStrategy} in [“renew”, “extend”, “drop”]  0 ~ 2147483646 Trigger expiration time (seconds) * Required if triggerStrategy is “renew”,“extend”,“drop” eventId string {triggerStrategy} in [“repeatCycleEnd”, “repeatCycleNextStart”, “absoluteEnd”]  ~ 1024 chars Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if triggerStrategy is “repeatCycleEnd”,“repeatCycleNextStart”,“absoluteEnd” timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Trigger Pulled Trigger Implementation Example extendTriggerByUserId Extend the period of a trigger by specifying a user ID Extends the expiration period of an existing trigger for the specified user by the specified number of seconds. If the trigger does not exist, a new trigger is created with the specified extension period as its TTL. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID extendSeconds int  0 ~ 2147483646 Trigger extension period (seconds) timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Trigger Pulled Trigger Implementation Example deleteTrigger Delete Trigger Deletes the specified trigger for the requesting user. Deleting a trigger deactivates associated relative schedule events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Trigger Trigger deleted Implementation Example deleteTriggerByUserId Delete Trigger by specifying a user ID Deletes the specified trigger for the specified user. Deleting a trigger deactivates associated relative schedule events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Trigger Trigger deleted Implementation Example verifyTrigger Verify the elapsed time since the trigger was pulled Verifies conditions related to the trigger’s state. The verifyType can be: ’notTriggerd’ to verify the trigger has not been pulled, ’elapsed’ to verify the specified minutes have elapsed since the trigger was pulled, or ’notElapsed’ to verify the specified minutes have not yet elapsed. Returns an error if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “notTriggerd”,   “elapsed”,   “notElapsed” }  Type of verification Definition Description “notTriggerd” Trigger not pulled “elapsed” Elapsed time “notElapsed” Not elapsed time elapsedMinutes int {verifyType} in [“elapsed”, “notElapsed”]  0 ~ 2147483646 Elapsed time (minutes) * Required if verifyType is “elapsed”,“notElapsed” Result Type Description item Trigger Trigger Implementation Example verifyTriggerByUserId Verify the elapsed time since the Trigger was pulled by specifying a user ID Verifies conditions related to the trigger’s state for the specified user. The verifyType can be: ’notTriggerd’, ’elapsed’, or ’notElapsed’. Returns an error if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “notTriggerd”,   “elapsed”,   “notElapsed” }  Type of verification Definition Description “notTriggerd” Trigger not pulled “elapsed” Elapsed time “notElapsed” Not elapsed time elapsedMinutes int {verifyType} in [“elapsed”, “notElapsed”]  0 ~ 2147483646 Elapsed time (minutes) * Required if verifyType is “elapsed”,“notElapsed” timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Trigger Trigger Implementation Example describeEvents Get a list of Events Retrieves a list of currently active events for the requesting user. Only events whose schedule is currently in progress are returned. For relative schedule events, the result depends on the user’s trigger state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of Events Implementation Example describeEventsByUserId Get a list of Events by specifying a user ID Retrieves a list of currently active events for the specified user. Only events whose schedule is currently in progress are returned. For relative schedule events, the result depends on the specified user’s trigger state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Events Implementation Example describeRawEvents Get a list of Events Retrieves a list of all event definitions in the namespace without filtering by user context or schedule status. Returns the raw event data regardless of whether events are currently active. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Events Implementation Example getEvent Get Event Retrieves the specified event along with its schedule status. Returns whether the event is currently in its active period, the schedule start/end times, repeat schedule information, and whether it is a global schedule. If isInSchedule is set to true and the event is not currently active, a NotFound error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token isInSchedule bool true Are only current events eligible for acquisition Result Type Description item Event Event inSchedule bool? Whether in schedule scheduleStartAt long Schedule start time scheduleEndAt long Schedule end time If the event type is absolute, the absoluteEnd of the EventModel is stored. If the event type is relative, scheduleEndAt stores either the trigger’s expiration time or the absoluteEnd of the EventModel, whichever ends sooner. repeatSchedule RepeatSchedule Repeat Schedule isGlobalSchedule bool? Is the event a global schedule Implementation Example getEventByUserId Get Event by specifying a user ID Retrieves the specified event along with its schedule status for the specified user. Returns whether the event is currently in its active period, the schedule start/end times, repeat schedule information, and whether it is a global schedule. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID isInSchedule bool true Are only current events eligible for acquisition timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Event Event inSchedule bool? Whether in schedule scheduleStartAt long Schedule start time scheduleEndAt long Schedule end time If the event type is absolute, the absoluteEnd of the EventModel is stored. If the event type is relative, scheduleEndAt stores either the trigger’s expiration time or the absoluteEnd of the EventModel, whichever ends sooner. repeatSchedule RepeatSchedule Repeat Schedule isGlobalSchedule bool? Is the event a global schedule Implementation Example getRawEvent Get Event Retrieves the raw event definition without user context. Returns the event data without evaluating the schedule status against a specific user’s trigger state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Event Event Implementation Example verifyEvent Verify if it is the event period Verifies whether the specified event is currently in its active schedule period. The verifyType can be set to ‘inSchedule’ to verify the event is active, or ’notInSchedule’ to verify it is not active. Returns an error if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “inSchedule”,   “notInSchedule” }  Type of verification Definition Description “inSchedule” The event is in its active period “notInSchedule” The event is not in its active period Result Type Description item Event Event inSchedule bool? Whether in schedule scheduleStartAt long Schedule start time scheduleEndAt long Schedule end time If the event type is absolute, the absoluteEnd of the EventModel is stored. If the event type is relative, scheduleEndAt stores either the trigger’s expiration time or the absoluteEnd of the EventModel, whichever ends sooner. repeatSchedule RepeatSchedule Repeat Schedule isGlobalSchedule bool? Is the event a global schedule Implementation Example verifyEventByUserId Verify whether the Event is active by specifying a user ID Verifies whether the specified event is currently in its active schedule period for the specified user. The verifyType can be set to ‘inSchedule’ or ’notInSchedule’. Returns an error if the verification condition is not met. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “inSchedule”,   “notInSchedule” }  Type of verification Definition Description “inSchedule” The event is in its active period “notInSchedule” The event is not in its active period timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Event Event inSchedule bool? Whether in schedule scheduleStartAt long Schedule start time scheduleEndAt long Schedule end time If the event type is absolute, the absoluteEnd of the EventModel is stored. If the event type is relative, scheduleEndAt stores either the trigger’s expiration time or the absoluteEnd of the EventModel, whichever ends sooner. repeatSchedule RepeatSchedule Repeat Schedule isGlobalSchedule bool? Is the event a global schedule Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently registered event masters in an activatable master data format. The exported data contains all event schedule definitions including absolute/relative timing, repeat settings, and trigger configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentEventMaster master data that can be activated Implementation Example getCurrentEventMaster Get currently active Event master data Retrieves the currently active event master data including all event schedule definitions that are being used for schedule evaluation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentEventMaster Currently active Event master data Implementation Example preUpdateCurrentEventMaster Update currently active Event master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentEventMaster Update currently active Event master data Updates the currently active event master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentEventMaster Updated master data of the currently active Event Implementation Example updateCurrentEventMasterFromGitHub Update currently active Event master data from GitHub Updates the currently active event master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentEventMaster Updated master data of the currently active Event Implementation Example describeEventMasters Get a list of Event Masters Retrieves a paginated list of event masters. Can filter by event name prefix. Event masters define event schedules including absolute/relative timing, repeat settings, and trigger associations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by event name prefix 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 List of Event masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createEventMaster Create a new Event Master Creates a new event master with schedule type (absolute or relative), begin/end times, repeat settings (daily, weekly, monthly), and optional trigger name for relative schedule events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. Result Type Description item EventMaster Event Master created Implementation Example getEventMaster Get Event Master Retrieves the specified event master including its schedule type, begin/end times, repeat settings, and trigger configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EventMaster Event master Implementation Example updateEventMaster Update Event Master Updates the specified event master’s schedule type, begin/end times, repeat settings, trigger configuration, and other properties. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. Result Type Description item EventMaster Event Master updated Implementation Example deleteEventMaster Delete Event Master Deletes the specified event master. Note that this only removes the master definition; the currently active event master data is not affected until the next master data update. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item EventMaster Event Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Schedule SDK for various programming languages\n","title":"GS2-Schedule SDK API Reference","url":"/api_reference/schedule/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when scripts return transaction actions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking script invocations and their results. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setup to check out script from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Script file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Script Script GS2 provides scripts to extend functionality when the standard functions are not sufficient. Scripts can be written in the Lua language. Scripts can also retrieve data from GS2 services, allowing for flexible processing. Please refer to the documentation for details. Details  scriptId string * ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description script string  ~ 5242880 chars Lua Script The Lua script source code to execute. Scripts can access GS2 service data and return results that modify the behavior of the calling service. disableStringNumberToNumber bool false Disable String-Number Conversion When enabled, strings consisting only of digits (e.g., “12345”) are kept as strings instead of being automatically converted to numbers. Useful when handling IDs or codes that should remain as string type even if they look numeric. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RandomStatus Random Number Status Manages the random number state available within a script execution context. Contains a seed value and a list of used random numbers per category. This state is passed to the Lua script as a table and can be read/modified by the script. Details  seed long  0 ~ 4294967294 Random Seed The seed value for random number generation. Used to produce deterministic random sequences within the script execution. used List 0 ~ 1000 items Used Random Numbers List of random numbers already consumed, categorized by purpose. Each category can have its own usage counter. RandomUsed Used Random Numbers Tracks the number of random values consumed for a specific category. Each category represents a distinct purpose for random number usage within script execution, allowing independent tracking of random consumption. Details  category long  0 ~ 4294967294 Category A numeric identifier for the random number usage category. Each category tracks random consumption independently, allowing scripts to use separate random sequences for different purposes. used long  0 ~ 4294967294 Used Count The number of random values that have been consumed in this category. Incremented each time a random number is drawn from this category’s sequence. AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Transaction Transaction Represents a set of actions to be executed as a distributed transaction returned from a script. Contains verify actions (precondition checks), consume actions (resource consumption), and acquire actions (resource granting), which are executed as a transaction. Details  transactionId string ~ 128 chars Transaction ID Optional unique identifier for this transaction. Used to track and deduplicate the execution of the acquire actions. verifyActions List 0 ~ 100 items List of Verify Actions List of verify actions that serve as preconditions for the transaction. All verify actions must pass before consume and acquire actions are executed. consumeActions List [] 0 ~ 100 items List of Acquire Actions List of consume actions that consume resources as part of the transaction. Executed after all verify actions pass. acquireActions List [] 0 ~ 100 items List of Acquire Actions List of acquire actions (transactions) that grant resources as part of the transaction. Executed after all consume actions complete successfully. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when scripts return transaction actions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking script invocations and their results. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when scripts return transaction actions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking script invocations and their results. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example describeScripts Get a list of Scripts Retrieves a paginated list of Lua scripts registered in the namespace. Can filter by script name prefix. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by script name prefix 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 List of Scripts nextPageToken string Page token to retrieve the rest of the listing Implementation Example createScript Create a new script Creates a new Lua script with the specified code. The disableStringNumberToNumber option controls whether strings consisting only of numbers are automatically converted to numbers during script execution. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description script string  ~ 5242880 chars Lua Script disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers Result Type Description item Script Script created Implementation Example createScriptFromGitHub Create a new script from code in the GitHub repository Creates a new script by checking out the source file from the specified GitHub repository. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description checkoutSetting GitHubCheckoutSetting  Setup to check out source code from GitHub disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers Result Type Description item Script Script created Implementation Example getScript Get Script Retrieves the specified script including its name, description, script code, and type conversion settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scriptName string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Script Script Implementation Example updateScript Update Script Updates the specified script’s code, description, and type conversion settings. The entire script code is replaced with the new content. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scriptName string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description script string  ~ 5242880 chars Lua Script disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers Result Type Description item Script Script updated Implementation Example updateScriptFromGitHub Update scripts using GitHub as a data source Updates an existing script by fetching the latest source code from the specified GitHub repository. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scriptName string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description checkoutSetting GitHubCheckoutSetting  Setup to check out source code from GitHub disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers Result Type Description item Script Script updated Implementation Example deleteScript Delete script Deletes the specified script from the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scriptName string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Script Script deleted Implementation Example invokeScript Execute the script Synchronously executes the specified Lua script with the provided JSON arguments. Returns the execution result including status code, return value, transaction information, random number state, execution time, and standard output. Supports transaction handling for atomic operations across GS2 services. Details Request  scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN userId string ~ 128 chars User ID args string “{}” ~ 5242880 chars Arguments (JSON Format) randomStatus RandomStatus Random number status timeOffsetToken string ~ 1024 chars Time offset token Result Type Description code int Status Code result string Result Value transaction Transaction Transaction randomStatus RandomStatus Random number status atomicCommit bool? Whether to commit the transaction atomically transactionResult TransactionResult Transaction execution result executeTime int Script execution time (milliseconds) charged int Time (seconds) for which costs were calculated output List List of contents of standard output Implementation Example debugInvoke Execute Script Executes the provided Lua script code directly for debugging purposes without requiring prior script registration, allowing rapid testing and development of scripts. Details Request  script string  ~ 5242880 chars Lua Script args string “{}” ~ 5242880 chars Arguments (JSON Format) userId string ~ 128 chars User ID randomStatus RandomStatus Random number status disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers timeOffsetToken string ~ 1024 chars Time offset token Result Type Description code int Status Code result string Result Value transaction Transaction Transaction randomStatus RandomStatus Random number status atomicCommit bool? Whether to commit the transaction atomically transactionResult TransactionResult Transaction execution result executeTime int Script execution time (milliseconds) charged int Time (seconds) for which costs were calculated output List List of contents of standard output Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Script SDK for various programming languages\n","title":"GS2-Script SDK API Reference","url":"/api_reference/script/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when applying season rating results. logSetting LogSetting Log Output Setting Configuration for logging season rating operations such as ballot issuance, vote submissions, and rating calculations. When set, operation logs are output to the specified GS2-Log namespace. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAtomicCommit bool false Whether to commit the execution of transactions atomically transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” MatchSession Match Session A temporary entity that manages the voting context for each match. Players obtain ballots from the MatchSession and finalize results through voting. It has a TTL (expiration time), and results are finalized upon majority vote or expiration. Details  sessionId string * ~ 1024 chars MatchSession A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Ballot Ballot A voting ticket issued to each player for a specific match session. Contains the match context (season, session, number of players) and the player’s user ID. The ballot is signed by the server and returned to the player, who then fills in game results and submits it back as part of a WrittenBallot. During vote aggregation, ballots from all participants are compared via majority consensus to prevent result manipulation. Details  userId string  ~ 128 chars User ID seasonName string  ~ 128 chars Season Name The name of the season model used for this match’s rating calculations. References the SeasonModel that defines the tier structure and point adjustment rules applied to this match. sessionName string  ~ 128 chars Session Name The name of the match session this ballot belongs to. All ballots within the same session are aggregated together during the voting process. numberOfPlayer int  2 ~ 10 Number of Players The total number of participants in this match. Determines when the vote is considered complete: all ballots must be collected (or majority achieved) before results are finalized. Valid range: 2 to 10. Vote Vote Aggregates the voting state for a specific match session within a season. Collects WrittenBallots from all participants and determines the official match result through majority consensus. The vote is considered complete when the number of submitted ballots reaches the expected number of players. If a majority (more than half) of ballots agree on the results, the outcome is finalized; otherwise, a “minority” error occurs. Details  voteId string * ~ 1024 chars Vote A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server seasonName string  ~ 128 chars Season Name The name of the season model associated with this vote. References the SeasonModel that defines the tier structure and point adjustment rules for this match. sessionName string  ~ 128 chars Session Name The name of the match session this vote belongs to. Combined with the season name, uniquely identifies the vote within the namespace. writtenBallots List [] 0 ~ 10 items List of Written Ballots The collection of submitted ballots from match participants. Each ballot is appended or replaced by user ID as players submit their results. When all expected players have submitted (or the session expires), the ballots are aggregated via majority consensus to determine the official match outcome. Maximum 10 entries (matching the maximum number of players per match). createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SeasonModel Season Model Defines the tier structure and point adjustment rules applied during a season. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience. Details  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. TierModel Tier Model TierModel defines the point adjustment rules for each tier within a season. Specifies point change ranges by rank, entry fees, and promotion bonuses. While actual point data is managed by GS2-Experience, the calculation logic for point adjustments is determined by the TierModel configuration. Details  metadata string ~ 128 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. raiseRankBonus int  0 ~ 10000 Raise Rank Bonus Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion. For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold. Valid range: 0 to 10000. entryFee int  0 ~ 10000 Entry Fee Points deducted from the player before the match begins as a participation cost. This fee is always subtracted regardless of the match outcome, creating a risk element in competitive play. Valid range: 0 to 10000. minimumChangePoint int  -99999999 ~ -1 Minimum Change Point The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss. Must be a negative value. The actual point change for a losing player falls between this value and 0. Valid range: -99999999 to -1. maximumChangePoint int  1 ~ 99999999 Maximum Change Point The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win. Must be a positive value. The actual point change for a winning player falls between 0 and this value. Valid range: 1 to 99999999. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution GameResult Match Result Represents the outcome of a single player in a match. Contains the player’s user ID and their finishing rank. Used within a WrittenBallot to report the results of all participants. During vote aggregation, game results are compared across all submitted ballots using majority consensus to determine the official outcome. Details  rank int  0 ~ 2147483646 Rank The finishing position of this player in the match. 1 indicates first place (winner). The rank value is used to determine point adjustments based on the TierModel configuration. userId string  ~ 128 chars User ID SignedBallot Signed Ballot A ballot that has been cryptographically signed by the server using GS2-Key. The signature ensures that the ballot content (season, session, player, number of participants) has not been tampered with. When submitting a vote, the signed ballot is verified server-side before the game results are accepted. Details  body string  ~ 1024 chars Body The serialized JSON representation of the ballot data that serves as the signature target. Contains the ballot content (user ID, season name, session name, number of players) in a format that can be verified against the signature. Maximum 1024 characters. signature string  ~ 256 chars Signature The cryptographic signature generated by GS2-Key for the ballot body. Used to verify that the ballot was issued by the server and has not been modified by the client. Base64-encoded, maximum 256 characters. WrittenBallot Written Ballot A data model representing a ballot with written match results. It contains user IDs and ranks, and is submitted with a signature to the Vote API. Details  ballot Ballot  Ballot The original ballot issued to the player for this match. Contains the match context (season, session, player ID, number of participants) and is used to identify the voter during aggregation. gameResults List 0 ~ 10 items List of Match Results The game results reported by this player, one entry per participant in the match. Each entry contains a user ID and rank. User IDs must be unique within the list (enforced by child_unique constraint). During vote aggregation, results are sorted by user ID and compared across all submitted ballots to reach majority consensus. Maximum 10 entries. CurrentSeasonModelMaster Currently active Season Model master data This master data defines the Season Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SeasonRating Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data SeasonModelMaster Season Model Master Season Model Master is data used to edit and manage Season Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Season Model actually referenced by the game. Season models are master data that define the tier structure and point fluctuation rules applicable during the season period. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience. Details  seasonModelId string * ~ 1024 chars Season Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when applying season rating results. logSetting LogSetting Log Output Setting Configuration for logging season rating operations such as ballot issuance, vote submissions, and rating calculations. When set, operation logs are output to the specified GS2-Log namespace. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when applying season rating results. logSetting LogSetting Log Output Setting Configuration for logging season rating operations such as ballot issuance, vote submissions, and rating calculations. When set, operation logs are output to the specified GS2-Log namespace. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeMatchSessions Get a list of MatchSessions Retrieves a paginated list of match sessions in the namespace. Match sessions represent individual matches and are used to group players for rating calculation. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 acquired Result Type Description items List List of MatchSession nextPageToken string Page token to retrieve the rest of the listing Implementation Example createMatchSession Create a MatchSession When you create a session, a session ID is issued. A session ID is required to send a report of the battle result, and by specifying the session ID, you can send a report for that session. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ttlSeconds int 60 60 ~ 7200 MatchSession expiration time (seconds) Result Type Description item MatchSession Created MatchSession Implementation Example getMatchSession Get MatchSession Retrieves the specified match session including its name and TTL information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MatchSession MatchSession Implementation Example deleteMatchSession Delete MatchSession Deletes the specified match session. Any pending votes associated with the session will also be invalidated. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MatchSession MatchSession deleted Implementation Example getBallot Prepared ballot along with signatures Issues a ballot for the requesting user to participate in a match session’s rating vote. Validates that the player is within the season’s challenge period, deducts any configured entry fee from the player’s rating, and generates a signed ballot using the specified encryption key. The signed ballot is then used when submitting vote or voteMultiple. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot body string Data to be signed signature string Signature Implementation Example getBallotByUserId Create ballot with signatures, specifying user ID Issues a ballot for the specified user to participate in a match session’s rating vote. Validates the challenge period, deducts entry fees, and generates a signed ballot using the specified encryption key. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  UUID ~ 128 chars Session name Session-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID numberOfPlayer int  2 ~ 10 Number of participants keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Ballot Ballot body string Data to be signed signature string Signature Implementation Example vote Vote on match results Voting must take place within 5 minutes of the first vote being cast. This means that the results will not be reflected immediately, but approximately 5 minutes after the start of voting or when all players have cast their votes. If all ballots are not collected within 5 minutes, the result will be determined by a majority vote based on the votes cast at that time. If you want to reflect the result immediately, the representative player of the winning side can collect ballots from each player and call voteMultiple to reflect the result immediately. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). ballotBody string  ~ 1024 chars Data for ballot signature targets ballotSignature string  ~ 256 chars Signature gameResults List 0 ~ 10 items Match Results List of user IDs belonging to the player group that participated in the match keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot Implementation Example voteMultiple Compile match results and vote The side that wins the game collects the ballots of other players and uses them to vote collectively. We say ’the winning side’ because there is an incentive for the losing side to report that they won, but not vice versa. It is possible that the losing side will not hand in their ballots, but even in that case, if there is a majority of ballots, the results can still be passed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). signedBallots List 0 ~ 10 items List of Ballot with signatures gameResults List 0 ~ 10 items List of Results keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN Result Type Description item Ballot Ballot Implementation Example commitVote Forced determination of voting status Manually triggers the rating calculation for a match session without waiting for all votes to be collected. Processes the pending votes, calculates rating changes based on the current vote state, and deletes the vote record and match session after processing. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). sessionName string  ~ 128 chars Session Name The name of the match session this vote belongs to. Combined with the season name, uniquely identifies the vote within the namespace. Result Type Description Implementation Example describeSeasonModels Get a list of Season Models Retrieves the list of currently active season models. Season models define the rating tiers, experience model reference, and challenge period event for seasonal rating calculations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Season Model Implementation Example getSeasonModel Get Season Model Retrieves the specified season model including its rating tiers, experience model reference, and challenge period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModel Season Model Implementation Example exportMaster Export Model Master in a master data format that can be activated Exports the currently registered season model masters in an activatable master data format. The exported data contains all season rating definitions including rating tiers, experience model references, and challenge period configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentSeasonModelMaster master data that can be activated Implementation Example getCurrentSeasonModelMaster Get currently active Season Model master data Retrieves the currently active season model master data including all season rating definitions that are being used for rating calculations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentSeasonModelMaster Currently active Season Model master data Implementation Example preUpdateCurrentSeasonModelMaster Update currently active Season Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentSeasonModelMaster Update currently active Season Model master data Updates the currently active season model master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentSeasonModelMaster Updated master data of the currently active Season Models Implementation Example updateCurrentSeasonModelMasterFromGitHub Update currently active Season Model master data from GitHub Updates the currently active season model master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentSeasonModelMaster Updated master data of the currently active Season Models Implementation Example describeSeasonModelMasters Get a list of Season Model Masters Retrieves a paginated list of season model masters. Can filter by name prefix. Season model masters define rating tiers, experience model reference, and challenge period event for seasonal rating. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Season Model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Season Model Master nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSeasonModelMaster Create a new Season Model Master Creates a new season model master with rating tiers, a reference to a GS2-Experience experience model for rating storage, and an optional challenge period event ID to restrict when players can participate. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. Result Type Description item SeasonModelMaster Created Rating Model Master Implementation Example getSeasonModelMaster Get Season Model Master Retrieves the specified season model master including its rating tiers, experience model reference, and challenge period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModelMaster Season Model Master Implementation Example updateSeasonModelMaster Update Season Model Master Updates the specified season model master’s rating tiers, experience model reference, challenge period event, and other properties. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. Result Type Description item SeasonModelMaster Season Model Master updated Implementation Example deleteSeasonModelMaster Delete Season Model Master Deletes the specified season model master. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SeasonModelMaster Season Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-SeasonRating SDK for various programming languages\n","title":"GS2-SeasonRating SDK API Reference","url":"/api_reference/season_rating/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing serial key operations. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to serial code issuance and usage. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” IssueJob Serial Code Issuance Job An entity is created when the serial code issuance process is executed. The quantity of serial codes issued can range from 1 to 100000, and the progress of the issuing process can be monitored. When the issuing process is completed, the status will change from PROCESSING to COMPLETE, and you will be able to access information about the serial code issued. Details  issueJobId string * ~ 1024 chars Issue Job A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  UUID ~ 36 chars Serial Code Issuance Job name 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. issuedCount int 0 0 ~ 1000000 Quantity of Serial Codes issued The number of serial codes that have been issued so far in this job. Incremented atomically as codes are created in batches. When this value reaches issueRequestCount, the job status transitions to COMPLETE. issueRequestCount int  1 ~ 100000 Quantity of Serial Codes to issue The total number of serial codes requested to be issued in this job. Can range from 1 to 100,000 per job. The issuance is processed asynchronously in batches. status string (enum) enum {   “PROCESSING”,   “COMPLETE” } “PROCESSING” Status The current processing status of this issuance job. Starts as PROCESSING when the job is created, and transitions to COMPLETE when all requested serial codes have been issued. Once COMPLETE, the issued serial codes can be retrieved. Definition Description “PROCESSING” Processing of issue “COMPLETE” Complete createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SerialKey Serial Code The serial code issued can be used only once. Serial codes are issued in the format “RPCLP-FP7N-NCDMJ-FLVA-IRI4” and the data length cannot be changed. Information on the type of campaign is also included within the serial code. When using the serial code, simply specify the namespace in which the serial code is to be used. Details  serialKeyId string * ~ 1024 chars Serial Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server campaignModelName string  ~ 128 chars Campaign name The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the namespace needs to be specified when using the code. code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. 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. status string (enum) enum {   “ACTIVE”,   “USED”,   “INACTIVE” } “ACTIVE” Status The current usage status of this serial code. Transitions from ACTIVE to USED when consumed by a user. The transition is protected by optimistic locking to prevent double-use. INACTIVE codes cannot be used. Definition Description “ACTIVE” Active “USED” Already used “INACTIVE” Disabled (cannot be used) usedUserId string {status} == “USED”  ~ 128 chars User ID * Required if status is “USED” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server usedAt long Used at The timestamp when this serial code was consumed. Set automatically when the status transitions to USED, and cleared if the usage is reverted. updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision CampaignModel Campaign Model A Campaign Model is used to define and manage campaigns, linking them to serial codes. Details  campaignId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Campaign Model * Set automatically by the server name string  ~ 128 chars Campaign Model name 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users. CurrentCampaignMaster Currently active Campaign Model master data This master data defines the Campaign Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SerialKey Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data CampaignModelMaster Campaign Model Master Data Campaign Model Master is data used to edit and manage Campaign Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Campaign Model actually referenced by the game. A Campaign Model is used to define and manage campaigns, linking them to serial codes. Details  campaignId string * ~ 1024 chars Campaign Model Master Data A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Campaign Model name description string ~ 1024 chars Description 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing serial key operations. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to serial code issuance and usage. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing serial key operations. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to serial code issuance and usage. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeIssueJobs Get a list of Serial Code Issuance Jobs Retrieves a paginated list of serial code issuance jobs for the specified campaign. Each job represents a batch issuance request and includes its completion status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Serial Code Issuance Jobs nextPageToken string Page token to retrieve the rest of the listing Implementation Example getIssueJob Get Serial Code Issuance Job Retrieves the specified serial code issuance job including its name, request count, metadata, and completion status. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name issueJobName string  UUID ~ 36 chars Serial Code Issuance Job name Result Type Description item IssueJob Serial Code Issuance Job Implementation Example issue Create a new Serial Code Issuance Job Initiates an asynchronous serial code generation job. The codes are generated in batches and a summary file is created upon completion. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name 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. issueRequestCount int  1 ~ 100000 Quantity of Serial Codes to issue The total number of serial codes requested to be issued in this job. Can range from 1 to 100,000 per job. The issuance is processed asynchronously in batches. Result Type Description item IssueJob Serial Code Issuance Job Implementation Example describeSerialKeys Get a list of Serial Codes Retrieves a paginated list of serial codes generated by a completed issuance job. The codes are loaded in parallel for efficient retrieval and paginated through an in-memory buffer. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name issueJobName string  UUID ~ 36 chars Serial Code Issuance Job name pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Serial Code nextPageToken string Page token to retrieve the rest of the listing Implementation Example downloadSerialCodes Get a list of serial codes by file Generates a pre-signed URL to download all serial codes from a completed issuance job as a file. This is suitable for bulk export of serial codes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name issueJobName string  UUID ~ 36 chars Serial Code Issuance Job name Result Type Description url string URL of file Implementation Example issueOnce Issue a serial code Issues a single serial code immediately. The code is generated using AES encryption and base32 encoding in the format XXXXX-XXXX-XXXXX-XXXX-XXXXX. Unlike batch issuance jobs, this generates and returns a code synchronously. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name 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. Result Type Description item SerialKey Serial Code Implementation Example getSerialKey Get serial code Retrieves the specified serial code along with its associated campaign model. Returns the code’s usage status and metadata. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example verifyCode Verify the validity of the serial code Verifies a serial code without consuming it. Supports verification against a specific campaign model name, and can check whether the code is active (unused) or inactive (already used). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. campaignModelName string ~ 128 chars Campaign name The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the namespace needs to be specified when using the code. verifyType string (enum) enum {   “active”,   “inactive” }  Verification type Definition Description “active” Active “inactive” Inactive Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example verifyCodeByUserId Verify the validity of the Serial Code by specifying a user ID Verifies a serial code for the specified user without consuming it. Supports verification against a specific campaign model name, and can check whether the code is active (unused) or inactive (already used). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. campaignModelName string ~ 128 chars Campaign name The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the namespace needs to be specified when using the code. verifyType string (enum) enum {   “active”,   “inactive” }  Verification type Definition Description “active” Active “inactive” Inactive timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example use Using serial code Marks a serial code as used by the current user. Validates that the code exists and has not already been used. Returns an error if the code is not found or has already been consumed. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example useByUserId Using Serial Code by specifying a user ID Marks a serial code as used by the specified user. Validates that the code exists and has not already been used. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example revertUseByUserId Serial Code set to unused by specifying a user ID Reverts a used serial code back to unused status. Validates that the code is currently in used state before reverting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SerialKey Serial Code campaignModel CampaignModel Campaign Model Implementation Example describeCampaignModels Get a list of Campaign Models Retrieves the list of currently active campaign models in the namespace. Campaign models define the serial code campaign configuration including whether campaign codes are enabled. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Campaign Model Implementation Example getCampaignModel Get Campaign Model Retrieves the specified campaign model including its name, metadata, and campaign code enablement setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name Result Type Description item CampaignModel Campaign Model Implementation Example exportMaster Export Campaign Model Master in a format that permits master data activation Exports the currently registered campaign model masters in an activatable master data format. The exported data contains all campaign definitions including campaign code enablement settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentCampaignMaster Campaign Model master data that can be activated Implementation Example getCurrentCampaignMaster Get currently active Campaign Model master data Retrieves the currently active campaign model master data including all campaign definitions that are being used for serial code management. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentCampaignMaster Currently active Campaign Model master data Implementation Example preUpdateCurrentCampaignMaster Update currently active Campaign Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentCampaignMaster Update currently active Campaign Model master data Updates the currently active campaign model master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update the master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentCampaignMaster Updated master data of the currently active Campaign Models Implementation Example updateCurrentCampaignMasterFromGitHub Update currently active Campaign Model master data from GitHub Updates the currently active campaign model master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentCampaignMaster Updated master data of the currently active Campaign Models Implementation Example describeCampaignModelMasters Get a list of Campaign Model Master Retrieves a paginated list of campaign model masters. Can filter by name prefix. Campaign model masters define serial code campaign configurations including campaign code enablement. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Campaign Model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Campaign Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createCampaignModelMaster Create a new Campaign Model Master Data Creates a new campaign model master with a name, description, metadata, and the enableCampaignCode flag that controls whether campaign codes can be used with this campaign. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Campaign Model name description string ~ 1024 chars Description 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users. Result Type Description item CampaignModelMaster Created Campaign Model Master Data Implementation Example getCampaignModelMaster Get a Campaign Model Master Data Retrieves the specified campaign model master including its name, description, metadata, and campaign code enablement setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name Result Type Description item CampaignModelMaster Campaign Model Master Data Implementation Example updateCampaignModelMaster Update Campaign Model Master Updates the specified campaign model master’s description, metadata, and campaign code enablement setting. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name description string ~ 1024 chars Description 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users. Result Type Description item CampaignModelMaster Campaign Model Master updated Implementation Example deleteCampaignModelMaster Delete Campaign Model Master Deletes the specified campaign model master. This only removes the master definition and does not affect the currently active campaign model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name Result Type Description item CampaignModelMaster Campaign Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-SerialKey SDK for various programming languages\n","title":"GS2-SerialKey SDK API Reference","url":"/api_reference/serial_key/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing showcase operations. buyScript ScriptSetting Script to run when attempting to execute a purchase Script Trigger Reference - buy logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to showcase browsing and product purchases. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Showcase Showcase A Showcase can define items for display. Additionally, the sales period for items on Showcase can be set. Details  showcaseId string * ~ 1024 chars Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Showcase name Showcase-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. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Controls the overall sales period of this showcase. When specified, the entire showcase is only available during the associated GS2-Schedule event period. If the event is not active, the showcase returns empty. displayItems List [] 1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. DisplayItem Displayed Item An item displayed on a showcase. Can reference either a single sales item or a sales item group. Each display item can have its own sales period controlled by a GS2-Schedule event, independently of the showcase-level sales period. Details  displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. type string (enum) enum {   “salesItem”,   “salesItemGroup” }  Type The type of item displayed. A “salesItem” is a single Sales Item with fixed price and rewards. A “salesItemGroup” contains multiple Sales Items evaluated in order, used for step-up pricing or limited purchase discounts. Definition Description “salesItem” Sales Item “salesItemGroup” Sales Item Group salesItem SalesItem {type} == “salesItem”  Sales Item * Required if type is “salesItem” salesItemGroup SalesItemGroup {type} == “salesItemGroup”  Sales Item Group * Required if type is “salesItemGroup” salesPeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with sales periods for this display item Controls the sales period of this individual display item. When specified, the item is only shown on the showcase during the associated GS2-Schedule event period. This is independent of the showcase-level sales period. RandomShowcase Random Showcase Random Showcase is a display model featuring randomly selected display items that rotate at specified intervals. The display item to be selected are randomly selected from the registered display items in the display item pool according to the specified quantity and the weight set for each display item. By associating a GS2-Schedule event with the Random Showcase, you can set its sales period. Details  randomShowcaseId string * ~ 1024 chars Random Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Random Showcase name Random Showcase-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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List [] 1 ~ 100 items List of Display Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Controls the overall sales period of this random showcase. When specified, the showcase is only available during the associated GS2-Schedule event period. RandomDisplayItem Random Displayed Item on the Random Showcase Represents a Sales Item that has been drawn and displayed on a random showcase for a specific user. Contains the item’s price, rewards, and purchase count tracking for the current rotation period. Details  showcaseName string  ~ 128 chars Random Showcase name name string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. 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. verifyActions List [] 0 ~ 10 items List of Verify Actions consumeActions List [] 0 ~ 10 items List of Consume Actions acquireActions List [] 1 ~ 100 items List of Acquire Actions currentPurchaseCount int  1 ~ 2147483646 Current purchase count The number of times this item has been purchased in the current rotation period. Incremented each time a purchase is made and reset when the rotation period ends. maximumPurchaseCount int  1 ~ 2147483646 Maximum purchase count The maximum number of times this item can be purchased in the current rotation period. Once currentPurchaseCount reaches this value, the item can no longer be purchased until the next rotation. RandomDisplayItemModel Items that can be displayed in a Random Showcase You can set the probability of selecting each item with weight . Details  name string  UUID ~ 128 chars Random Displayed Item ID Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before purchasing this Random Displayed Item. All verify actions must pass before consume and acquire actions are processed. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price for this Random Displayed Item. Executed as consume actions in the transaction. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards for this Random Displayed Item. Executed as acquire actions in the transaction. stock int  1 ~ 2147483646 Stock The maximum number of times this item can be drawn across all rotations. Once stock reaches zero, the item is excluded from future draws. Stock is consumed when the item is selected during a rotation draw. weight int  1 ~ 2147483646 Draw Weight The relative probability weight for this item in the random selection. Higher weights increase the chance of being drawn. The actual selection probability is calculated as this item’s weight divided by the sum of all eligible items’ weights. SalesItem Sales Item Defines the price required to purchase a Sales Item and the rewards granted upon purchase. Details  name string  ~ 128 chars Sales Item name Sales Item-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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. SalesItemGroup Sales Item Group A Sales Item Group is an entity for display on a Showcase. Multiple Sales Items can belong to a Sales Item Group. Sales Items are evaluated in order, and the first Sales Item determined to be available for purchase is displayed on the Showcase. This can be used for Sales Items that are discounted only for the first purchase, or for systems where the contents change based on the number of purchases, such as a step-up gacha. Details  name string  ~ 128 chars Sales Item Group name Sales Item Group-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. salesItems List [] 2 ~ 10 items Sales Items included in the Sales Item Group Ordered list of sales items in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. PurchaseCount Number of Random Displayed Item purchases Tracks the purchase count for a specific Random Displayed Item within a rotation period. Incremented when a purchase is made and decremented when a purchase is reverted. Details  name string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. count int  1 ~ 2147483646 Purchase count The number of times this item has been purchased in the current rotation period. Used to enforce the per-item maximum purchase limit. ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name The variable name to be substituted in the transaction template. Corresponds to a placeholder in the transaction action parameters. value string ~ 51200 chars Value The value to substitute for the corresponding variable name in the transaction template. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentShowcaseMaster Currently active Showcase Model master data This master data defines the Showcase Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Showcase Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data SalesItemMaster Sales Item Master Sales Item Master is data used to edit and manage Sales Item within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Sales Item actually referenced by the game. Set the price required to purchase the Sales Item and the reward you will receive for purchasing the Sales Item. Details  salesItemId string * ~ 1024 chars Sales Item Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. verifyActions List 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List  1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision SalesItemGroupMaster Sales Item Group Master Sales Item Group Master is data used to edit and manage Sales Item Group within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Sales Item Group actually referenced by the game. A Sales Item Group is an entity for display on a Showcase. Multiple Sales Items can belong to a Sales Item Group. Sales Items are evaluated in order, and the first Sales Item determined to be available for purchase is displayed on the Showcase. This can be used for Sales Items that are discounted only for the first time, or for a system in which the contents of Sales Items change depending on the number of times they are purchased, such as a step-up gacha. Details  salesItemGroupId string * ~ 1024 chars Sales Item Group Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. salesItemNames List  2 ~ 10 items List of Sales Items included in the Sales Item Group Ordered list of Sales Item names in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision ShowcaseMaster Showcase Master Showcase Master is data used to edit and manage Showcase within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Showcase actually referenced by the game. The sales period can be set for Showcase . Details  showcaseId string * ~ 1024 chars Showcase Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Controls the overall sales period of this showcase. When specified, the entire showcase is only available during the associated GS2-Schedule event period. If the event is not active, the showcase returns empty. displayItems List  1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision DisplayItemMaster Displayed Item Master Data Master data for an item displayed on a showcase. Can reference either a single Sales Item or a Sales Item Group by name. Each display item can have its own sales period controlled by a GS2-Schedule event, independently of the showcase-level sales period. Details  displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. type string (enum) enum {   “salesItem”,   “salesItemGroup” }  Type The type of item displayed. A “salesItem” is a single Sales Item with fixed price and rewards. A “salesItemGroup” contains multiple Sales Items evaluated in order, used for step-up pricing or limited purchase discounts. Definition Description “salesItem” Sales Item “salesItemGroup” Sales Item Group salesItemName string {type} == “salesItem”  ~ 128 chars Sales Item name The name of the sales item to display. Used when the display item type is “salesItem” to reference a specific Sales Item defined in the sales item master. * Required if type is “salesItem” salesItemGroupName string {type} == “salesItemGroup”  ~ 128 chars Sales Item Group name The name of the sales item group to display. Used when the display item type is “salesItemGroup” to reference a Sales Item Group that evaluates multiple items based on purchase count. * Required if type is “salesItemGroup” salesPeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with sales periods for this display item Controls the sales period of this individual display item. When specified, the item is only shown on the showcase during the associated GS2-Schedule event period. This is independent of the showcase-level sales period. revision long 0 0 ~ 9223372036854775805 Revision RandomShowcaseMaster Random Showcase Master Random Showcase Master is data used to edit and manage Random Showcase within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Random Showcase actually referenced by the game. Random Showcase is a display model featuring randomly selected display items that rotate at specified intervals. The display item to be selected are randomly selected from the registered display items in the display item pool according to the specified quantity and the weight set for each display item. By associating an event of GS2-Schedule with the Random Showcase, you can set the sales period. Details  showcaseId string * ~ 1024 chars Random Showcase Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List  1 ~ 100 items List of Random Displayed Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Controls the overall sales period of this random showcase. When specified, the showcase is only available during the associated GS2-Schedule event period. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing showcase operations. buyScript ScriptSetting Script to run when attempting to execute a purchase Script Trigger Reference - buy logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to showcase browsing and product purchases. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing showcase operations. buyScript ScriptSetting Script to run when attempting to execute a purchase Script Trigger Reference - buy logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to showcase browsing and product purchases. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeShowcases Get a list of Showcases Retrieves the list of active showcases available to the current user. Only showcases that are currently active based on the sales period event configuration are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of Showcases Implementation Example describeShowcasesByUserId Get a list of Showcases by specifying a user ID Retrieves the list of active showcases available to the specified user. Only showcases that are currently active based on the sales period event configuration are returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Showcases Implementation Example getShowcase Get Showcase Retrieves the specified Showcase with its Sales Items for the current user. The Showcase must be active based on the sales period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description item Showcase Showcase Implementation Example getShowcaseByUserId Get Showcase by specifying a user ID Retrieves the specified Showcase with its Sales Items for the specified user. The Showcase must be active based on the sales period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Showcase Showcase Implementation Example buy Buy Sales Item Purchases a Sales Item from the specified Showcase. Generates a transaction that processes the configured verify, consume, and acquire actions defined in the sales item. Configuration values can be passed to override transaction variables. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. accessToken string  ~ 128 chars Access token quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item SalesItem Sales Item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example buyByUserId Buy Sales Item by specifying a user ID Purchases a display item from the specified showcase for the specified user. Generates a transaction that processes the configured verify, consume, and acquire actions defined in the sales item. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. userId string  ~ 128 chars User ID quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item SalesItem Sales Item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example incrementPurchaseCount Increment the number of times a Random Displayed Item has been purchased Increments the purchase count for a specific Random Displayed Item in the Random Showcase. Used for tracking purchase limits per rotation period. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name displayItemName string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. accessToken string  ~ 128 chars Access token count int  0 ~ 100 Number of purchase times to add Result Type Description item RandomDisplayItem Randomly displayed items after purchase counts are added Implementation Example incrementPurchaseCountByUserId Increment the number of times a Random Displayed Item has been purchased by specifying the user ID Increments the purchase count for a specific Random Displayed Item in the Random Showcase for the specified user. Used for tracking purchase limits per rotation period. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name displayItemName string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. userId string  ~ 128 chars User ID count int  0 ~ 100 Number of purchase times to add timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RandomDisplayItem Randomly displayed items after purchase counts are added Implementation Example decrementPurchaseCountByUserId Decrement the number of times a Random Displayed Item has been purchased by specifying the user ID Decrements the purchase count for a specific Random Displayed Item in the Random Showcase. Used to reverse purchases or adjust purchase counters. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name displayItemName string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. userId string  ~ 128 chars User ID count int  0 ~ 100 Number of purchase times to subtract timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RandomDisplayItem Random Displayed Items after purchase counts are added Implementation Example forceReDrawByUserId Re-draw the contents of the Random Showcase by specifying a user ID Forces a redraw of the random showcase items for the specified user, resetting the current selection and triggering a new random item selection from the configured pool. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Random Displayed Items Implementation Example describeRandomDisplayItems Get a list of Random Displayed Items Retrieves the list of Random Displayed Items currently shown on the Random Showcase for the current user. The items are randomly selected from the configured pool and rotate based on the reset interval. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token Result Type Description items List List of Displayed Items on Random Showcase Implementation Example describeRandomDisplayItemsByUserId Get a list of Random Displayed Items on Random Showcase by specifying a user ID Retrieves the list of Random Displayed Items currently shown on the Random Showcase for the specified user. The items are randomly selected from the configured pool and rotate based on the reset interval. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Displayed Items on Random Showcase Implementation Example getRandomDisplayItem Get Random Displayed Item on Random Showcase Retrieves the specified Random Displayed Item from the Random Showcase for the current user. The Random Showcase must be available based on the sales period event. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. accessToken string  ~ 128 chars Access token Result Type Description item RandomDisplayItem Displayed item Implementation Example getRandomDisplayItemByUserId Get Random Displayed Item on Random Showcase by specifying a user ID Retrieves the specified Random Displayed Item from the Random Showcase for the specified user. The Random Showcase must be available based on the sales period event. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RandomDisplayItem Displayed item Implementation Example randomShowcaseBuy Purchase Random Displayed Item from Random Showcase Purchases a Random Displayed Item from the Random Showcase. Generates a transaction that processes the configured verify, consume, and acquire actions. Configuration values can be passed to override transaction variables. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. accessToken string  ~ 128 chars Access token quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item RandomDisplayItem Displayed item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example randomShowcaseBuyByUserId Purchase Random Displayed Item from Random Showcase by specifying a user ID Purchases a Random Displayed Item from the Random Showcase for the specified user. Generates a transaction that processes the configured verify, consume, and acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayItemName string  UUID ~ 128 chars Random Displayed Item name Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. userId string  ~ 128 chars User ID quantity int 1 1 ~ 1000 Purchase quantity config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item RandomDisplayItem Displayed item transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the purchase process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example exportMaster Export Showcase Master in a master data format that can be activated Exports the currently registered showcase masters in an activatable master data format. The exported data contains all showcase, sales item, sales item group, and random showcase definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentShowcaseMaster Showcase master data that can be activated Implementation Example getCurrentShowcaseMaster Get currently active Showcase master data Retrieves the currently active showcase master data including all showcase, sales item, sales item group, and random showcase definitions that are being used. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentShowcaseMaster Currently active Showcase master data Implementation Example preUpdateCurrentShowcaseMaster Update currently active Showcase master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentShowcaseMaster Update currently active Showcase master data Updates the currently active showcase master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentShowcaseMaster Updated master data of the currently active Showcase Implementation Example updateCurrentShowcaseMasterFromGitHub Update currently active Showcase master data from GitHub Updates the currently active showcase master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentShowcaseMaster Updated master data of the currently active Showcase Implementation Example describeSalesItemMasters Get a list of Sales Item Masters Retrieves a paginated list of sales item masters. Can filter by name prefix. Sales item masters define the verify, consume, and acquire actions that are executed when a product is purchased. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by product name prefix 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 List of Sales Item Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSalesItemMaster Create a new Sales Item Master Creates a new sales item master with verify actions (pre-purchase validation), consume actions (resources to deduct), and acquire actions (resources to grant) that define the complete purchase transaction. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. verifyActions List 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List  1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. Result Type Description item SalesItemMaster Sales Item Master created Implementation Example getSalesItemMaster Get Sales Item Master Retrieves the specified sales item master including its verify, consume, and acquire actions configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemName string  ~ 128 chars Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SalesItemMaster Sales Item Master Implementation Example updateSalesItemMaster Update Sales Item Master Updates the specified sales item master’s description, metadata, verify actions, consume actions, and acquire actions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemName string  ~ 128 chars Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. verifyActions List 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List  1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. Result Type Description item SalesItemMaster Sales Item Master updated Implementation Example deleteSalesItemMaster Delete Sales Item Master Deletes the specified sales item master. This only removes the master definition and does not affect the currently active showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemName string  ~ 128 chars Sales Item name Sales Item-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SalesItemMaster Sales Item Master deleted Implementation Example describeSalesItemGroupMasters Get a list of Sales Item Group Masters Retrieves a paginated list of Sales Item Group masters. Can filter by name prefix. Sales Item Group masters bundle multiple sales items together for display in a showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Sales Item Group name prefix 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 List of Sales Item Group Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createSalesItemGroupMaster Create a new Sales Item Group Master Creates a new Sales Item Group master with a name, metadata, and a list of Sales Item names that belong to the group. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. salesItemNames List  2 ~ 10 items List of Sales Items included in the Sales Item Group Ordered list of Sales Item names in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. Result Type Description item SalesItemGroupMaster Sales Item Group Master created Implementation Example getSalesItemGroupMaster Get Sales Item Group Master Retrieves the specified Sales Item Group master including its member Sales Item names list. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemGroupName string  ~ 128 chars Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SalesItemGroupMaster Sales Item Group Master Implementation Example updateSalesItemGroupMaster Update Sales Item Group Master Updates the specified sales item group master’s description, metadata, and list of member sales item names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemGroupName string  ~ 128 chars Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. salesItemNames List  2 ~ 10 items List of Sales Items included in the Sales Item Group Ordered list of Sales Item names in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. Result Type Description item SalesItemGroupMaster Sales Item Group Master updated Implementation Example deleteSalesItemGroupMaster Delete Sales Item Group Master Deletes the specified sales item group master. This only removes the master definition and does not affect the currently active showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). salesItemGroupName string  ~ 128 chars Sales Item Group name Sales Item Group-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item SalesItemGroupMaster Sales Item Group Master deleted Implementation Example describeShowcaseMasters Get a list of Showcase Masters Retrieves a paginated list of showcase masters. Can filter by name prefix. Showcase masters define the display items and sales period event for each showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by showcase name prefix 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 List of Showcase Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createShowcaseMaster Create a new Showcase Master Creates a new showcase master with a name, display items, metadata, and an optional sales period event ID to control when the showcase is available to users. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. displayItems List  1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Result Type Description item ShowcaseMaster Showcase Master created Implementation Example getShowcaseMaster Get Showcase Master Retrieves the specified showcase master including its display items, metadata, and sales period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ShowcaseMaster Showcase master Implementation Example updateShowcaseMaster Update Showcase Master Updates the specified showcase master’s description, metadata, display items, and sales period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. displayItems List  1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Result Type Description item ShowcaseMaster Showcase Master updated Implementation Example deleteShowcaseMaster Delete Showcase Master Deletes the specified showcase master. This only removes the master definition and does not affect the currently active showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Showcase name Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item ShowcaseMaster Showcase Master deleted Implementation Example describeRandomShowcaseMasters Get a list of Random Showcase Masters Retrieves a paginated list of random showcase masters. Can filter by name prefix. Random showcase masters define item pools, maximum display count, rotation timing, and sales period events. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Random Showcase name prefix 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 List of Random Showcase Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRandomShowcaseMaster Create a new Random Showcase Master Creates a new Random Showcase Master with the maximum number of items to display, a pool of Random Displayed Items, a base timestamp, reset interval in hours for item rotation, and an optional sales period event ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List  1 ~ 100 items List of Random Displayed Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Result Type Description item RandomShowcaseMaster Random Showcase Master created Implementation Example getRandomShowcaseMaster Get Random Showcase Master Retrieves the specified random showcase master including its display item pool, maximum display count, rotation timing settings, and sales period event configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RandomShowcaseMaster Random Showcase Master Implementation Example updateRandomShowcaseMaster Update Random Showcase Master Updates the specified Random Showcase Master’s description, metadata, Random Displayed Item pool, maximum display count, rotation timing, and sales period event. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List  1 ~ 100 items List of Random Displayed Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Result Type Description item RandomShowcaseMaster Random Showcase Master updated Implementation Example deleteRandomShowcaseMaster Delete Random Showcase Master Deletes the specified Random Showcase Master. This only removes the master definition and does not affect the currently active Random Showcase. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase name Random Showcase-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RandomShowcaseMaster Random Showcase Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Showcase SDK for various programming languages\n","title":"GS2-Showcase SDK API Reference","url":"/api_reference/showcase/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when executing node release and restrain operations. Defines how consume actions (release costs) and acquire actions (restrain refunds) are processed through the GS2 transaction system. releaseScript ScriptSetting Script to run when a node is released Script Trigger Reference - release restrainScript ScriptSetting Script to run when a node is restrained Script Trigger Reference - restrain logSetting LogSetting Log Output Setting Configuration for logging skill tree operations such as node releases, restrains, and resets. When set, operation logs are output to the specified GS2-Log namespace. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Status Status Tracks the skill tree release state for a specific player and property. Maintains a list of released (unlocked) node names. Nodes can be released (added to the list), restrained (removed from the list), or reset (all cleared). Attempting to release an already-released node or restrain a non-released node results in an error. Auto-created when first accessed for a user. Details  statusId string * ~ 1024 chars Status A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. releasedNodeNames List [] 0 ~ 1000 items Released Node Names List of node model names that the player has unlocked in this skill tree. Updated by release (add), restrain (remove), and reset (clear all) operations. Maximum 1000 entries. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision NodeModel Node Model Defines a node within the skill tree, including its unlock cost, prerequisites, and refund behavior. Each node can have verify actions (conditions to check before release), consume actions (costs to pay), and prerequisite nodes that must be released first. When a node is restrained (reverted to unreleased), the consumed resources are partially refunded based on the restrain return rate. The return acquire actions are automatically calculated from the consume actions multiplied by the restrain return rate. Details  nodeModelId string * ~ 1024 chars Node Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Node Model name Node 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. releaseVerifyActions List [] 0 ~ 10 items List of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. returnAcquireActions List 0 ~ 10 items Return Acquire Actions List of acquire actions executed when restraining (reverting) this node, representing the resources returned to the player. This field is auto-generated from the release consume actions multiplied by the restrain return rate. For example, if release costs 100 gold and the return rate is 0.8, restraining returns 80 gold. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. Config Configuration Configuration values applied to transaction variables Details  key string  ~ 64 chars Name value string ~ 51200 chars Value ConsumeAction Consume Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action Details  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution CurrentTreeMaster Currently active Node Model master data This master data defines the Node Models currently active within the Namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SkillTree Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data NodeModelMaster Node Model Master Node Model Master is data used to edit and manage Node Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Node Model actually referenced by the game. Each node defines its unlock cost (consume actions), release conditions (verify actions), prerequisite nodes, and refund behavior (restrain return rate). When a node is restrained, the consumed resources are partially refunded based on the return rate. The return acquire actions are automatically calculated. Details  nodeModelId string * ~ 1024 chars Node Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. releaseVerifyActions List [] 0 ~ 10 items list of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when executing node release and restrain operations. Defines how consume actions (release costs) and acquire actions (restrain refunds) are processed through the GS2 transaction system. releaseScript ScriptSetting Script to run when a node is released Script Trigger Reference - release restrainScript ScriptSetting Script to run when a node is restrained Script Trigger Reference - restrain logSetting LogSetting Log Output Setting Configuration for logging skill tree operations such as node releases, restrains, and resets. When set, operation logs are output to the specified GS2-Log namespace. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when executing node release and restrain operations. Defines how consume actions (release costs) and acquire actions (restrain refunds) are processed through the GS2 transaction system. releaseScript ScriptSetting Script to run when a node is released Script Trigger Reference - release restrainScript ScriptSetting Script to run when a node is restrained Script Trigger Reference - restrain logSetting LogSetting Log Output Setting Configuration for logging skill tree operations such as node releases, restrains, and resets. When set, operation logs are output to the specified GS2-Log namespace. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example markReleaseByUserId Mark a node as released by specifying a user ID Validates that the specified nodes can be released (prerequisite nodes must already be released), then marks them as released. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example release Release a node Releases the specified nodes in the skill tree by generating a transaction. The transaction includes release verify actions (pre-release validation) and release consume actions (resource deduction) defined in the node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the release process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example releaseByUserId Release a node by specifying a user ID Releases the specified nodes in the skill tree by generating a transaction. The transaction includes release verify actions (pre-release validation) and release consume actions (resource deduction) defined in the node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the release process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example markRestrain Revert a node to unreleased state Validates that the specified nodes can be restrained (no dependent nodes must be in released state), then marks them as unreleased. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of node model names Result Type Description item Status Status Implementation Example markRestrainByUserId Revert a node to unreleased state by specifying a user ID Validates that the specified nodes can be restrained (no dependent nodes must be in released state), then marks them as unreleased. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of node model names timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example restrain Restrain a node Reverts the specified nodes to unreleased state by generating a transaction. Resources consumed during the original release are partially returned based on the restrain return rate configured in the node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the restrain process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example restrainByUserId Restrain a node by specifying a user ID Reverts the specified nodes to unreleased state by generating a transaction. Resources consumed during the original release are partially returned based on the restrain return rate configured in the node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the restrain process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeStatuses List statuses Retrieves a paginated list of skill tree statuses for the requesting user. Each status contains the release state of all nodes in the skill tree for a specific property ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of status nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStatusesByUserId Get a list of statuses by specifying a user ID Retrieves a paginated list of skill tree statuses for the specified user. Each status contains the release state of all nodes in the skill tree for a specific property ID. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of status nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStatus Get a status Retrieves the skill tree status for the requesting user and the specified property ID. The status includes the list of released node names and their current states. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. Result Type Description item Status Status Implementation Example getStatusByUserId Get status by specifying a user ID Retrieves the skill tree status for the specified user and property ID. The status includes the list of released node names and their current states. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status Implementation Example reset Reset status Resets the skill tree status by reverting all released nodes to unreleased state. Generates a transaction that returns resources based on the restrain return rate configured in each node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. config List [] 0 ~ 32 items Configuration values applied to transaction variables Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reset process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example resetByUserId Reset status by specifying a user ID Resets the skill tree status by reverting all released nodes to unreleased state. Generates a transaction that returns resources based on the restrain return rate configured in each node model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status transactionId string Issued transaction ID stampSheet string Stamp sheet used to execute the reset process stampSheetEncryptionKeyId string Cryptographic key GRN used for stamp sheet signature calculations autoRunStampSheet bool? Whether automatic transaction execution is enabled atomicCommit bool? Whether to commit the transaction atomically transaction string Issued transaction transactionResult TransactionResult Transaction execution result Implementation Example describeNodeModels Get a list of Node Models Retrieves the list of active node models in the skill tree. Each node model defines release verification and consume actions, restrain return rate, and prerequisite node names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Node Models Implementation Example getNodeModel Get Node Model Retrieves the specified node model including its release verify actions, release consume actions, restrain return rate, and prerequisite node names configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). nodeModelName string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item NodeModel Node Model Implementation Example exportMaster Export Node Model Master in a master data format that can be activated Exports the currently registered node model masters in an activatable master data format. The exported data contains all node model definitions including release actions, restrain return rates, and prerequisite node configurations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentTreeMaster Node Model master data that can be activated Implementation Example getCurrentTreeMaster Get currently active Node Model master data Retrieves the currently active node model master data including all node model definitions with their release actions, restrain return rates, and prerequisite node configurations that are being used. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentTreeMaster Currently active Node Model master data Implementation Example preUpdateCurrentTreeMaster Update Currently Active Master Data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentTreeMaster Update currently active Node Model master data Updates the currently active node model master data. Supports both direct update mode and pre-upload mode for handling large master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentTreeMaster Updated master data of the currently active Node Models Implementation Example updateCurrentTreeMasterFromGitHub Update currently active Node Model master data from GitHub Updates the currently active node model master data by checking out master data from a GitHub repository using the specified checkout settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentTreeMaster Updated master data of the currently active Node Models Implementation Example describeNodeModelMasters Get a list of Node Model Masters Retrieves a paginated list of node model masters. Can filter by name prefix. Node model masters define the skill tree structure including release actions, restrain return rate, and prerequisite nodes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by node model name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Node Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNodeModelMaster Create a new Node Model Master Creates a new node model master with release verify actions (pre-release validation), release consume actions (resources to deduct on release), restrain return rate (percentage of resources returned on restrain), and prerequisite node names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. releaseVerifyActions List [] 0 ~ 10 items list of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. Result Type Description item NodeModelMaster Created Node Model Master Implementation Example getNodeModelMaster Get Node Model Master Retrieves the specified node model master including its release verify actions, release consume actions, restrain return rate, and prerequisite node names configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). nodeModelName string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item NodeModelMaster Node Model Master Implementation Example updateNodeModelMaster Update Node Model Master Updates the specified node model master’s description, metadata, release verify actions, release consume actions, restrain return rate, and prerequisite node names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). nodeModelName string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. releaseVerifyActions List [] 0 ~ 10 items list of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. Result Type Description item NodeModelMaster Node Model Master updated Implementation Example deleteNodeModelMaster Delete Node Model Master Deletes the specified node model master. This only removes the master definition and does not affect the currently active skill tree. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). nodeModelName string  ~ 128 chars Node Model name Node Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item NodeModelMaster Node Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-SkillTree SDK for various programming languages\n","title":"GS2-SkillTree SDK API Reference","url":"/api_reference/skill_tree/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing stamina operations. overflowTriggerScript string ~ 1024 chars Overflow Trigger Script GRN of a GS2-Script to invoke when stamina overflows during recovery. This script is triggered when time-based recovery would push stamina above the maximum value, allowing custom handling of the excess (e.g., converting overflow to items). Script Trigger Reference - overflow logSetting LogSetting Log Output Setting Configuration for logging stamina-related operations such as consume, recover, and overflow events to GS2-Log. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” Stamina Stamina Stamina is a point that is recovered over time in real time. Generally, this stamina is used to limit the number of times a player can play a game per day and to allow the game provider to control the speed of game progression by allowing players to consume stamina to play the game. Details  staminaId string * ~ 1024 chars Stamina A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID value int  0 ~ 2147483646 Stamina Value The current stamina amount for this user, excluding any overflow. This value increases automatically over time based on the recovery interval and recovery value, up to maxValue. It is computed from the elapsed time since lastRecoveredAt using the formula: recoverSteps = elapsedMinutes / recoverIntervalMinutes. maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. recoverIntervalMinutes int 1 ~ 2147483646 Stamina Recovery Interval (Minutes) The per-user recovery interval in minutes, resolved from the StaminaModel and optionally overridden by a RecoverIntervalTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverIntervalMinutes. recoverValue int 1 ~ 2147483646 Stamina Recovery Amount The per-user recovery amount per tick, resolved from the StaminaModel and optionally overridden by a RecoverValueTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverValue. overflowValue int  0 ~ 2147483646 Overflow Value The amount of stamina stored in excess of the normal maximum (maxValue). This is only used when the StaminaModel has isOverflow enabled. The total effective stamina is value + overflowValue, capped at maxCapacity. When stamina is consumed, overflow is consumed first before the base value. nextRecoverAt long Next Recovery Time The Unix timestamp (in milliseconds) when the next stamina recovery tick will occur. Calculated as lastRecoveredAt + recoverIntervalMinutes (in ms). When stamina is already at maxValue, this field may be unset. lastRecoveredAt long * Current time Datetime of last recovery Unix time, milliseconds *Automatically configured on the server createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision StaminaModel Stamina Model Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience. Details  staminaModelId string * ~ 1024 chars Stamina Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. For example, if initialCapacity is 100 and maxCapacity is 200, items can boost stamina up to 200 but natural recovery stops at 100. * Required if isOverflow is true maxStaminaTable MaxStaminaTable Max Stamina Table Reference to a MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. If not set, all players share the same initialCapacity as their maximum. recoverIntervalTable RecoverIntervalTable Recover Interval Table Reference to a RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table using their current rank index, overriding recoverIntervalMinutes. If not set, all players share the same recoverIntervalMinutes. recoverValueTable RecoverValueTable Recover Value Table Reference to a RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table using their current rank index, overriding recoverValue. If not set, all players share the same recoverValue. MaxStaminaTable Maximum Stamina Table This entity defines the maximum value of stamina for each rank of GS2-Experience. Details  name string  ~ 128 chars Maximum Stamina Table Name Maximum Stamina Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. RecoverIntervalTable Recovery Interval Table This entity defines the stamina recovery interval for each rank of GS2-Experience. Details  name string  ~ 128 chars Stamina recovery interval table name Stamina recovery interval table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. RecoverValueTable Stamina Recovery Amount Table This entity defines the amount of stamina recovery for each rank of GS2-Experience. Details  name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue. CurrentStaminaMaster Currently active Stamina Model master data This master data defines the Stamina Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Stamina Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data StaminaModelMaster Stamina Model Master Stamina Model Master is data used to edit and manage Stamina Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Stamina Model actually referenced by the game. Parameters such as maximum stamina value, recovery interval, and recovery amount can be defined. It can also be linked to GS2-Experience to control the maximum value and the amount of recovery. Details  staminaModelId string * ~ 1024 chars Stamina Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. * Required if isOverflow is true maxStaminaTableName string ~ 128 chars Max Stamina Table Name Name of the MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. recoverIntervalTableName string ~ 128 chars Recover Interval Table Name Name of the RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table, overriding recoverIntervalMinutes. recoverValueTableName string ~ 128 chars Recover Value Table Name Name of the RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table, overriding recoverValue. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision MaxStaminaTableMaster Maximum Stamina Table Master Maximum Stamina Table Master is data used to edit and manage maximum stamina table within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as maximum stamina table actually referenced by the game. This entity defines the maximum value of stamina for each rank in GS2-Experience. Details  maxStaminaTableId string * ~ 1024 chars Maximum Stamina Table Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Maximum Stamina Value Table Name Maximum Stamina Value Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RecoverIntervalTableMaster Recovery Interval Table Master Recovery Interval Table Master is data used to edit and manage Recovery Interval Table within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Recovery Interval Table actually referenced by the game. This entity defines the stamina recovery interval for each rank of GS2-Experience. Details  recoverIntervalTableId string * ~ 1024 chars Recovery Interval Table Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Recovery Interval Table name Recovery Interval Table-specific name.-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision RecoverValueTableMaster Stamina Recovery Amount Table Master Stamina Recovery Amount Table Master is data used to edit and manage Stamina Recovery Amount Table within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Stamina Recovery Amount Table actually referenced by the game. This entity defines the amount of stamina recovery for each rank of GS2-Experience. Details  recoverValueTableId string * ~ 1024 chars Stamina Recovery Amount Table Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. description string ~ 1024 chars Description experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing stamina operations. overflowTriggerScript string ~ 1024 chars Overflow Trigger Script GRN of a GS2-Script to invoke when stamina overflows during recovery. This script is triggered when time-based recovery would push stamina above the maximum value, allowing custom handling of the excess (e.g., converting overflow to items). Script Trigger Reference - overflow logSetting LogSetting Log Output Setting Configuration for logging stamina-related operations such as consume, recover, and overflow events to GS2-Log. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing stamina operations. overflowTriggerScript string ~ 1024 chars Overflow Trigger Script GRN of a GS2-Script to invoke when stamina overflows during recovery. This script is triggered when time-based recovery would push stamina above the maximum value, allowing custom handling of the excess (e.g., converting overflow to items). Script Trigger Reference - overflow logSetting LogSetting Log Output Setting Configuration for logging stamina-related operations such as consume, recover, and overflow events to GS2-Log. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeStaminas Get a list of Stamina Retrieves a paginated list of all stamina resources for the requesting user. Each stamina entry contains the current value, maximum value, recovery settings, and overflow amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Staminas nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStaminasByUserId Get Stamina list by specifying a user ID Retrieves a paginated list of all stamina resources for the specified user. Each stamina entry contains the current value, maximum value, recovery settings, and overflow amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Staminas nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStamina Get Stamina Retrieves the specified stamina resource along with its stamina model. Returns the current stamina value, maximum value, recovery interval, recovery value, and overflow amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example getStaminaByUserId Get Stamina by specifying a user ID Retrieves the specified stamina resource along with its stamina model for the given user. Returns the current stamina value, maximum value, recovery interval, recovery value, and overflow amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example updateStaminaByUserId Create and update Stamina by specifying a user ID Manually sets all stamina properties at once including current value, maximum value, recovery interval, and recovery value. This is an administrative operation for direct overrides, preserving the current overflow and last recovered timestamp. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID value int  0 ~ 2147483646 Stamina Value The current stamina amount for this user, excluding any overflow. This value increases automatically over time based on the recovery interval and recovery value, up to maxValue. It is computed from the elapsed time since lastRecoveredAt using the formula: recoverSteps = elapsedMinutes / recoverIntervalMinutes. maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. recoverIntervalMinutes int 1 ~ 2147483646 Stamina Recovery Interval (Minutes) The per-user recovery interval in minutes, resolved from the StaminaModel and optionally overridden by a RecoverIntervalTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverIntervalMinutes. recoverValue int 1 ~ 2147483646 Stamina Recovery Amount The per-user recovery amount per tick, resolved from the StaminaModel and optionally overridden by a RecoverValueTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverValue. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example consumeStamina Consume Stamina Deducts the specified amount from the current stamina value. Returns an Insufficient error if the current stamina value is less than the consume amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token consumeValue int  1 ~ 2147483646 Amount of stamina consumed Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example consumeStaminaByUserId Consume Stamina by specifying a user ID Deducts the specified amount from the current stamina value for the given user. Returns an Insufficient error if the current stamina value is less than the consume amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID consumeValue int  1 ~ 2147483646 Amount of stamina consumed timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example applyStamina Apply the natural recovery amount of the current stamina Computes and applies the time-based automatic stamina recovery. The recovery amount is calculated based on the elapsed time since the last recovery, the recovery interval, and the recovery value configured in the stamina model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example applyStaminaByUserId Apply the natural recovery amount of the current stamina by specifying the user ID Computes and applies the time-based automatic stamina recovery for the specified user. The recovery amount is calculated based on the elapsed time since the last recovery, the recovery interval, and the recovery value configured in the stamina model. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example recoverStaminaByUserId Recover Stamina by specifying a user ID Recovers stamina by the specified amount up to the maximum capacity. If the recovery causes the value to exceed the maximum and overflow mode is enabled, the excess is tracked as an overflow value. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID recoverValue int  1 ~ 2147483646 Amount of stamina recovery timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model overflowValue int Stamina value transferred to GS2-Inbox without receiving more than the maximum Stamina value Implementation Example raiseMaxValueByUserId Add the maximum value of stamina by specifying the user ID Permanently increases the maximum stamina capacity by the specified amount. Used for permanent stat increases such as level-up rewards or item effects. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID raiseValue int  0 ~ 2147483646 Maximum amount of stamina to be increased timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example decreaseMaxValue Subtract the maximum value of stamina Reduces the maximum stamina capacity by the specified amount. May be used to apply debuffs or penalties to stamina capacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token decreaseValue int  0 ~ 2147483646 Maximum amount of stamina to be decreased Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example decreaseMaxValueByUserId Subtract the maximum value of stamina by specifying the user ID Reduces the maximum stamina capacity by the specified amount for the given user. May be used to apply debuffs or penalties to stamina capacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID decreaseValue int  0 ~ 2147483646 Maximum amount of stamina to be decreased timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setMaxValueByUserId Update the maximum value of stamina by specifying a user ID Sets the maximum stamina capacity to the specified value. The old stamina state is preserved in the response for audit purposes. Used for administrative overrides or special event adjustments. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setRecoverIntervalByUserId Update stamina recovery interval (minutes) by specifying a user ID Sets the stamina recovery interval to the specified value in minutes. The old stamina state is preserved in the response for audit purposes. Controls how frequently the stamina recovers automatically. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID recoverIntervalMinutes int  1 ~ 2147483646 Stamina recovery interval (minutes) timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setRecoverValueByUserId Set the amount of stamina recovery by specifying the user ID Sets the stamina recovery amount to the specified value. The old stamina state is preserved in the response for audit purposes. Controls how much stamina is recovered per recovery interval. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID recoverValue int  1 ~ 2147483646 Amount of stamina recovery timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setMaxValueByStatus Update maximum stamina using GS2-Experience status Sets the maximum stamina capacity based on the rank value from a signed GS2-Experience status. The signed status body and signature are verified using the specified key, then the rank value is used to look up the corresponding maximum stamina from the max stamina table. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setRecoverIntervalByStatus Update stamina recovery interval using GS2-Experience status Sets the stamina recovery interval based on the rank value from a signed GS2-Experience status. The signed status body and signature are verified using the specified key, then the rank value is used to look up the corresponding recovery interval from the recover interval table. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example setRecoverValueByStatus Update stamina recovery amount using GS2-Experience status Sets the stamina recovery amount based on the rank value from a signed GS2-Experience status. The signed status body and signature are verified using the specified key, then the rank value is used to look up the corresponding recovery amount from the recover value table. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. accessToken string  ~ 128 chars Access token keyId string “grn:gs2:{region}:{ownerId}:key:default:key:default” ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN signedStatusBody string  ~ 524288 chars GS2-Experience status body to be signed signedStatusSignature string  ~ 128 chars GS2-Experience Status Signature Result Type Description item Stamina Stamina old Stamina Stamina staminaModel StaminaModel Stamina Model Implementation Example deleteStaminaByUserId Delete Stamina by specifying a user ID Permanently deletes the specified stamina resource for the given user. This removes the stamina record entirely including its current value, recovery settings, and overflow amount. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina deleted Implementation Example verifyStaminaValue Verify the value of the current stamina Validates that the current stamina value meets the specified condition (less, lessEqual, greater, greaterEqual, equal, notEqual) against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Stamina Stamina Implementation Example verifyStaminaValueByUserId Verify the value of the current Stamina by specifying a user ID Validates that the current stamina value for the specified user meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina Implementation Example verifyStaminaMaxValue Verify the value of the max stamina Validates that the maximum stamina capacity (including buff modifications) meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Stamina Stamina Implementation Example verifyStaminaMaxValueByUserId Verify the value of the max stamina by specifying a user ID Validates that the maximum stamina capacity (including buff modifications) for the specified user meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina Implementation Example verifyStaminaRecoverIntervalMinutes Verify the value of the recovery interval minutes Validates that the stamina recovery interval (minutes) meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Stamina Stamina Implementation Example verifyStaminaRecoverIntervalMinutesByUserId Verify the value of the recovery interval minutes by specifying a user ID Validates that the stamina recovery interval (minutes) for the specified user meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina Implementation Example verifyStaminaRecoverValue Verify the value of the recovery value Validates that the stamina recovery amount (including buff modifications) meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Stamina Stamina Implementation Example verifyStaminaRecoverValueByUserId Verify the value of the recovery value by specifying a user ID Validates that the stamina recovery amount (including buff modifications) for the specified user meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina Implementation Example verifyStaminaOverflowValue Verify the value of the overflow value Validates that the stamina overflow amount (excess stamina beyond maximum capacity) meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity Result Type Description item Stamina Stamina Implementation Example verifyStaminaOverflowValueByUserId Verify the value of the overflow value by specifying a user ID Validates that the stamina overflow amount for the specified user meets the specified condition against the given threshold without modifying any state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Stamina Stamina Implementation Example describeStaminaModels Get a list of Stamina Models Retrieves the list of active stamina models. Each stamina model defines recovery interval, recovery value, initial capacity, overflow settings, and optional lookup tables for level-based stamina parameters. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Stamina Models Implementation Example getStaminaModel Get Stamina Model Retrieves the specified stamina model including its recovery interval, recovery value, initial capacity, overflow configuration, and linked lookup table names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item StaminaModel Stamina Model Implementation Example exportMaster Export Stamina Model Master in a master data format that can be activated Exports the currently registered stamina model masters in an activatable master data format. The exported data contains all stamina model, maximum stamina table, recovery interval table, and recovery amount table definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentStaminaMaster Stamina Model master data that can be activated Implementation Example getCurrentStaminaMaster Get currently active Stamina Model master data Retrieves the currently active stamina model master data including all stamina model, maximum stamina table, recovery interval table, and recovery amount table definitions that are being used. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentStaminaMaster Currently active Stamina Model master data Implementation Example preUpdateCurrentStaminaMaster Update currently active Stamina Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentStaminaMaster Update currently active Stamina Model master data Updates the currently active stamina model master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentStaminaMaster Updated master data of the currently active Stamina Models Implementation Example updateCurrentStaminaMasterFromGitHub Update currently active Stamina Model master data from GitHub Updates the currently active stamina model master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentStaminaMaster Updated master data of the currently active Stamina Models Implementation Example describeStaminaModelMasters Get a list of Stamina Model Masters Retrieves a paginated list of stamina model masters. Can filter by name prefix. Stamina model masters define recovery interval, recovery value, initial capacity, overflow settings, and optional lookup table associations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Stamina Model name prefix 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 List of Stamina Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createStaminaModelMaster Create a new Stamina Model Master Creates a new stamina model master with recovery interval (minutes), recovery value, initial capacity, overflow mode setting, maximum capacity, and optional associations to max stamina table, recover interval table, and recover value table for level-based parameter scaling. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. * Required if isOverflow is true maxStaminaTableName string ~ 128 chars Max Stamina Table Name Name of the MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. recoverIntervalTableName string ~ 128 chars Recover Interval Table Name Name of the RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table, overriding recoverIntervalMinutes. recoverValueTableName string ~ 128 chars Recover Value Table Name Name of the RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table, overriding recoverValue. Result Type Description item StaminaModelMaster Stamina Model Master created Implementation Example getStaminaModelMaster Get Stamina Model Master Retrieves the specified stamina model master including its recovery settings, capacity configuration, overflow mode, and linked lookup table names. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item StaminaModelMaster Stamina Model Master Implementation Example updateStaminaModelMaster Update Stamina Model Master Updates the specified stamina model master’s description, metadata, recovery interval, recovery value, initial capacity, overflow settings, maximum capacity, and lookup table associations. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. * Required if isOverflow is true maxStaminaTableName string ~ 128 chars Max Stamina Table Name Name of the MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. recoverIntervalTableName string ~ 128 chars Recover Interval Table Name Name of the RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table, overriding recoverIntervalMinutes. recoverValueTableName string ~ 128 chars Recover Value Table Name Name of the RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table, overriding recoverValue. Result Type Description item StaminaModelMaster Stamina Model Master updated Implementation Example deleteStaminaModelMaster Delete Stamina Model Master Deletes the specified stamina model master. This only removes the master definition and does not affect the currently active stamina configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item StaminaModelMaster Stamina Model Master deleted Implementation Example describeMaxStaminaTableMasters Get a list of Maximum Stamina Table Masters Retrieves a paginated list of maximum stamina table masters. These tables map experience rank values to maximum stamina capacity, enabling level-based stamina scaling. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 List of Maximum Stamina Table Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createMaxStaminaTableMaster Create a new Maximum Stamina Table Master Creates a new maximum stamina table master with an experience model ID and a values array. The values array is indexed by experience rank, mapping each rank to the corresponding maximum stamina capacity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Maximum Stamina Value Table Name Maximum Stamina Value Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. Result Type Description item MaxStaminaTableMaster Maximum Stamina Table Master created Implementation Example getMaxStaminaTableMaster Get Maximum Stamina Table Master Retrieves the specified maximum stamina table master including its experience model association and rank-to-capacity values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). maxStaminaTableName string  ~ 128 chars Maximum Stamina Value Table Name Maximum Stamina Value Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MaxStaminaTableMaster Maximum Stamina Table Master Implementation Example updateMaxStaminaTableMaster Update Maximum Stamina Table Master Updates the specified maximum stamina table master’s description, metadata, experience model association, and rank-to-capacity values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). maxStaminaTableName string  ~ 128 chars Maximum Stamina Value Table Name Maximum Stamina Value Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. Result Type Description item MaxStaminaTableMaster Maximum Stamina Table Master updated Implementation Example deleteMaxStaminaTableMaster Delete Maximum Stamina Table Master Deletes the specified maximum stamina table master. This only removes the master definition and does not affect the currently active stamina configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). maxStaminaTableName string  ~ 128 chars Maximum Stamina Value Table Name Maximum Stamina Value Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item MaxStaminaTableMaster Maximum Stamina Table Master deleted Implementation Example describeRecoverIntervalTableMasters Get a list of Recovery Interval Table Masters Retrieves a paginated list of recovery interval table masters. Can filter by name prefix. These tables map experience rank values to stamina recovery interval (minutes), enabling level-based recovery speed scaling. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by Recovery Interval Table name prefix 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 List of Recovery Interval Table Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRecoverIntervalTableMaster Create a new Recovery Interval Table Master Creates a new recovery interval table master with an experience model ID and a values array. The values array is indexed by experience rank, mapping each rank to the corresponding recovery interval in minutes. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Recovery Interval Table name Recovery Interval Table-specific name.-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. Result Type Description item RecoverIntervalTableMaster Recovery Interval Table Master created Implementation Example getRecoverIntervalTableMaster Get Recovery Interval Table Master Retrieves the specified recovery interval table master including its experience model association and rank-to-interval values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverIntervalTableName string  ~ 128 chars Recovery Interval Table name Recovery Interval Table-specific name.-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RecoverIntervalTableMaster Stamina recovery interval table master Implementation Example updateRecoverIntervalTableMaster Update Recovery Interval Table Master Updates the specified recovery interval table master’s description, metadata, experience model association, and rank-to-interval values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverIntervalTableName string  ~ 128 chars Recovery Interval Table name Recovery Interval Table-specific name.-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. Result Type Description item RecoverIntervalTableMaster Recovery Interval Table Master updated Implementation Example deleteRecoverIntervalTableMaster Delete Recovery Interval Table Master Deletes the specified recovery interval table master. This only removes the master definition and does not affect the currently active stamina configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverIntervalTableName string  ~ 128 chars Recovery Interval Table name Recovery Interval Table-specific name.-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RecoverIntervalTableMaster Recovery Interval Table Master deleted Implementation Example describeRecoverValueTableMasters Get a list of Stamina Recovery Amount Table Masters Retrieves a paginated list of stamina recovery amount table masters. Can filter by name prefix. These tables map experience rank values to stamina recovery amounts per interval, enabling level-based recovery amount scaling. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by stamina recovery amount table name prefix 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 List of Stamina Recovery Amount Table Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createRecoverValueTableMaster Create a new Stamina Recovery Amount Table Master Creates a new stamina recovery amount table master with an experience model ID and a values array. The values array is indexed by experience rank, mapping each rank to the corresponding recovery amount per interval. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue. Result Type Description item RecoverValueTableMaster Stamina Recovery Amount Table Master created Implementation Example getRecoverValueTableMaster Get Stamina Recovery Amount Table Master Retrieves the specified stamina recovery amount table master including its experience model association and rank-to-recovery-amount values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverValueTableName string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RecoverValueTableMaster Stamina recovery amount table master Implementation Example updateRecoverValueTableMaster Update Stamina Recovery Amount Table Master Updates the specified stamina recovery amount table master’s description, metadata, experience model association, and rank-to-recovery-amount values mapping. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverValueTableName string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue. Result Type Description item RecoverValueTableMaster Stamina Recovery Amount Table Master updated Implementation Example deleteRecoverValueTableMaster Delete Stamina Recovery Amount Table Master Deletes the specified stamina recovery amount table master. This only removes the master definition and does not affect the currently active stamina configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). recoverValueTableName string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item RecoverValueTableMaster Stamina Recovery Amount Table Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Stamina SDK for various programming languages\n","title":"GS2-Stamina SDK API Reference","url":"/api_reference/stamina/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description supportSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to support speculative execution When enabled, state machine definitions and random status are embedded in the Status entity, allowing clients to simulate state transitions locally before server confirmation. Requires transactionSetting to be configured. Definition Description “enable” Enable “disable” Disable transactionSetting TransactionSetting {supportSpeculativeExecution} == “enable” Transaction Settings Configuration for controlling how transactions are processed when executing state machine emit actions. Required when speculative execution is enabled. * Enabled only if supportSpeculativeExecution is “enable” startScript ScriptSetting Script to execute when starting the state machine Script Trigger Reference - start passScript ScriptSetting Script to execute when the state machine is successfully completed Script Trigger Reference - pass errorScript ScriptSetting Script to execute when the state machine fails Script Trigger Reference - error lowestStateMachineVersion long Lowest version of the state machine The minimum acceptable version for running state machines. Status instances created with a state machine version older than this value will be rejected, ensuring all running instances use up-to-date definitions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to state machine execution, state transitions, and emit events. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed upon completion Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts Used when you want to know the completion of the done script. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Status State Machine Status Represents a running instance of a state machine for a specific user. Tracks the current execution state including variables, call stack for sub-state machines, transition count, and random number state. The status transitions through Running, Wait, Pass (success), and Error states. Details  statusId string * ~ 1024 chars Status of State Machine A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server userId string  ~ 128 chars User ID name string  UUID ~ 36 chars Status name Maintains a unique name for each status of state machine. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each status of state machine. stateMachineVersion long  0 ~ 32503680000000 Version The version identifier of this state machine definition. Automatically assigned on creation. Used in combination with lowestStateMachineVersion on the namespace to enforce version compatibility for running instances. enableSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to enable speculative execution When enabled, the state machine definition and random status are included in this Status entity. This allows clients to simulate transitions locally before server confirmation, reducing perceived latency. Definition Description “enable” Enable “disable” Disable stateMachineDefinition string {enableSpeculativeExecution} == “enable” ~ 16777216 chars State machine definition The GSL definition embedded in this status for speculative execution. Only present when enableSpeculativeExecution is enabled. Filtered out in normal API responses and only included when needed for client-side simulation. * Enabled only if enableSpeculativeExecution is “enable” randomStatus RandomStatus {enableSpeculativeExecution} == “enable” Random status The random number generation state for this execution instance. Used for speculative execution to ensure deterministic random behavior across client and server. Only present when enableSpeculativeExecution is enabled. * Enabled only if enableSpeculativeExecution is “enable” stacks List [] 0 ~ 1024 items Stack The call stack for sub-state machine invocations. When a state machine calls a sub-state machine, an entry is pushed with the caller’s state machine name and return task. When the sub-state machine completes, the entry is popped and execution resumes at the return task. variables List [] 0 ~ 1000 items State variables for each state machine The current variable values for each state machine in the call hierarchy. Each entry holds the state machine name and a JSON-serialized value supporting int, float, string, bool, array, and map types. Variables persist across state transitions within the same execution instance. status string (enum) enum {   “Running”,   “Wait”,   “Pass”,   “Error” } “Running” Status The current execution status of this state machine instance. “Running” means the machine is actively processing transitions. “Wait” means the machine is waiting for an external event (emit). “Pass” means it completed successfully. “Error” means it terminated with an error. Definition Description “Running” Running “Wait” Wait “Pass” Pass “Error” Error lastError string ~ 1024 chars Last error The error message from the most recent failure. Set when the status transitions to “Error”. Contains details about what caused the state machine to terminate abnormally. transitionCount int 0 0 ~ 2147483645 Number of transitions The total number of state transitions performed in this execution instance. Incremented on each transition. If this value exceeds 1000, the state machine is terminated with an error to prevent infinite loops. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server StackEntry Stack Entry Represents a single entry in the sub-state machine call stack. When a state machine invokes a sub-state machine, the caller’s name and the return task are pushed onto the stack. When the sub-state machine completes, execution resumes at the return task of the popped entry. Details  stateMachineName string  ~ 128 chars Name of the state machine The name of the calling state machine that pushed this stack entry. Used to identify which state machine’s context to restore when returning from a sub-state machine. taskName string  ~ 128 chars Task name The name of the task (state) to return to when the sub-state machine completes. Execution resumes from this task in the calling state machine. Variable State variables per state machine Holds the current variable state for a specific state machine within the call hierarchy. The value is a JSON-serialized representation supporting int, float, string, bool, array, and map data types. Details  stateMachineName string  ~ 128 chars Name of the state machine The name of the state machine that owns these variables. In a nested call hierarchy, each state machine has its own independent variable scope identified by this name. value string  ~ 1048576 chars Value The JSON-serialized variable values for this state machine. Supports int, float, string, bool, array, and map data types. Updated as the state machine processes transitions and actions. Event Event Represents an event that occurred during state machine execution. Can be either a state change event (recording a state transition) or an emit event (sending a message to trigger external actions). Details  eventType string (enum) enum {   “change_state”,   “emit” }  Event type The type of event. “change_state” records a state transition within the state machine. “emit” represents a message sent to trigger external actions such as granting rewards or consuming resources. Definition Description “change_state” Change state “emit” Send a message changeStateEvent ChangeStateEvent {eventType} == “change_state”  Change state * Required if eventType is “change_state” emitEvent EmitEvent {eventType} == “emit”  Send a message * Required if eventType is “emit” ChangeStateEvent Change state event Records a state transition that occurred within the state machine. Contains the destination task name, a hash for integrity verification, and the timestamp of the transition. Details  taskName string  ~ 128 chars Task name The name of the destination task (state) that the state machine transitioned to. hash string  ~ 64 chars Hash A hash value for verifying the integrity of the state transition. Used to validate that the transition was performed correctly and the state is consistent. timestamp long  Timestamp EmitEvent Send a message event Represents a message emitted by the state machine to trigger external actions. The event name identifies the type of action, and parameters provide the action-specific data. Details  event string  ~ 128 chars Event name The name identifying the type of emitted event. Used to determine which external action to invoke, such as granting rewards or consuming resources. parameters string  ~ 1024 chars Parameters The parameters passed with the emitted event. Contains action-specific data in a serialized format that is used to configure the external action triggered by this event. timestamp long  Timestamp RandomStatus Random number status Manages the random number generation state for a state machine execution instance. Contains a seed value and per-category usage tracking. Used for speculative execution to ensure deterministic random behavior across client and server. Details  seed long  0 ~ 4294967294 Random seed The seed value for deterministic random number generation within the state machine execution. used List 0 ~ 1000 items List of used random number Tracks random numbers consumed per category. Each category represents a distinct purpose for random number usage, allowing independent tracking to maintain consistency across speculative re-executions. RandomUsed Used random number Tracks the number of random values consumed for a specific category within a state machine execution. Each category allows independent random number tracking for different purposes. Details  category long  0 ~ 4294967294 Category A numeric identifier for the random number usage category. Each category tracks random consumption independently, allowing the state machine to use separate random sequences for different purposes. used long  0 ~ 4294967294 Used count The number of random values that have been consumed in this category. Incremented each time a random number is drawn from this category’s sequence. VerifyActionResult Verify Action execution result Details  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 ConsumeActionResult Consume Action execution result Details  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 AcquireActionResult Acquire Action execution result Details  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 TransactionResult Transaction execution result Result of a transaction executed using the server-side automatic execution feature Details  transactionId string  36 ~ 36 chars Transaction ID verifyResults List 0 ~ 10 items List of verify action execution results consumeResults List [] 0 ~ 10 items List of Consume Action execution results acquireResults List [] 0 ~ 100 items List of Acquire Action execution results hasError bool false Whether an error occurred during transaction execution StateMachineMaster State machine definition Manages state machines written in GSL. Details  stateMachineId string * ~ 1024 chars State Machine Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server mainStateMachineName string  ~ 128 chars Main state machine name The name of the entry-point state machine in the GSL definition. Execution begins from this state machine, which can call sub-state machines via the stack mechanism. payload string  ~ 5242880 chars State machine definition The GSL (GS2 State Language) source code that defines the state machine’s states, transitions, and actions. Stored separately from the metadata for efficient retrieval. version long  0 ~ 32503680000000 Version The version identifier of this state machine definition. Automatically assigned on creation. Used in combination with lowestStateMachineVersion on the namespace to enforce version compatibility for running instances. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description supportSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to support speculative execution When enabled, state machine definitions and random status are embedded in the Status entity, allowing clients to simulate state transitions locally before server confirmation. Requires transactionSetting to be configured. Definition Description “enable” Enable “disable” Disable transactionSetting TransactionSetting {supportSpeculativeExecution} == “enable” Transaction Settings Configuration for controlling how transactions are processed when executing state machine emit actions. Required when speculative execution is enabled. * Enabled only if supportSpeculativeExecution is “enable” startScript ScriptSetting Script to execute when starting the state machine Script Trigger Reference - start passScript ScriptSetting Script to execute when the state machine is successfully completed Script Trigger Reference - pass errorScript ScriptSetting Script to execute when the state machine fails Script Trigger Reference - error lowestStateMachineVersion long Lowest version of the state machine The minimum acceptable version for running state machines. Status instances created with a state machine version older than this value will be rejected, ensuring all running instances use up-to-date definitions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to state machine execution, state transitions, and emit events. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description supportSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to support speculative execution When enabled, state machine definitions and random status are embedded in the Status entity, allowing clients to simulate state transitions locally before server confirmation. Requires transactionSetting to be configured. Definition Description “enable” Enable “disable” Disable transactionSetting TransactionSetting {supportSpeculativeExecution} == “enable” Transaction Settings Configuration for controlling how transactions are processed when executing state machine emit actions. Required when speculative execution is enabled. * Enabled only if supportSpeculativeExecution is “enable” startScript ScriptSetting Script to execute when starting the state machine Script Trigger Reference - start passScript ScriptSetting Script to execute when the state machine is successfully completed Script Trigger Reference - pass errorScript ScriptSetting Script to execute when the state machine fails Script Trigger Reference - error lowestStateMachineVersion long Lowest version of the state machine The minimum acceptable version for running state machines. Status instances created with a state machine version older than this value will be rejected, ensuring all running instances use up-to-date definitions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to state machine execution, state transitions, and emit events. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeStatuses Get a list of state machine statuses Retrieves a paginated list of state machine statuses for the requesting user. Can filter by status (Running, Pass, Error) to retrieve only state machines in a specific state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token status string (enum) enum {   “Running”,   “Wait”,   “Pass”,   “Error” } Status The current execution status of this state machine instance. “Running” means the machine is actively processing transitions. “Wait” means the machine is waiting for an external event (emit). “Pass” means it completed successfully. “Error” means it terminated with an error. Definition Description “Running” Running “Wait” Wait “Pass” Pass “Error” Error pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired Result Type Description items List List of Status of State Machine nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeStatusesByUserId Get a list of State Machine Statuses by specifying a user ID Retrieves a paginated list of state machine statuses for the specified user. Can filter by status (Running, Pass, Error) to retrieve only state machines in a specific state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID status string (enum) enum {   “Running”,   “Wait”,   “Pass”,   “Error” } Status The current execution status of this state machine instance. “Running” means the machine is actively processing transitions. “Wait” means the machine is waiting for an external event (emit). “Pass” means it completed successfully. “Error” means it terminated with an error. Definition Description “Running” Running “Wait” Wait “Pass” Pass “Error” Error pageToken string ~ 1024 chars Token specifying the position from which to start acquiring data limit int 30 1 ~ 1000 Number of data acquired timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Status of State Machine nextPageToken string Page token to retrieve the rest of the listing Implementation Example getStatus Get State Machine Status Retrieves the state machine status for the requesting user, including the current state, variables, stack trace, and error information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token statusName string  ~ 36 chars Status name Result Type Description item Status State Machine Status Implementation Example getStatusByUserId Get State Machine Status by specifying a user ID Retrieves the state machine status for the specified user, including the current state, variables, stack trace, and error information. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID statusName string  ~ 36 chars Status name timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status State Machine Status Implementation Example startStateMachineByUserId Start state machine by specifying a user ID Starts a new state machine instance for the specified user using the latest master version. Arguments are passed as JSON and parsed into state machine variables. An optional TTL (in minutes) can be set; if omitted, the state machine remains valid for approximately 10 years. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID args string “{}” ~ 4096 chars Arguments to be passed to the state machine ttl int 1 ~ 525600 Validity period (minutes) timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Started state machine Implementation Example emit Send an event to the state machine Sends a named event with JSON arguments to the state machine, triggering a state transition. If the state machine version is lower than the namespace’s lowestStateMachineVersion, the status is automatically deleted and a NotFound error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token statusName string  ~ 36 chars Status name eventName string  ~ 36 chars Event name args string “{}” ~ 4096 chars Arguments to be passed to the state machine Result Type Description item Status Status of State Machine Implementation Example emitByUserId Send an event to the state machine by specifying a user ID Sends a named event with JSON arguments to the state machine for the specified user, triggering a state transition. If the state machine version is lower than the namespace’s lowestStateMachineVersion, the status is automatically deleted and a NotFound error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID statusName string  ~ 36 chars Status name eventName string  ~ 36 chars Event name args string “{}” ~ 4096 chars Arguments to be passed to the state machine timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status of State Machine Implementation Example report Report multiple events to the state machine Reports a batch of events that were processed on the client side using speculative execution. The server replays the events to validate the state transitions. If the resulting state does not match the client’s reported state, a StateMismatch error is returned. Requires speculative execution to be enabled on the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token statusName string  ~ 36 chars Status name events List 0 ~ 1000 items List of events Result Type Description item Status Status of State Machine Implementation Example reportByUserId Report multiple events to the state machine by specifying a user ID Reports a batch of events that were processed on the client side using speculative execution for the specified user. The server replays the events to validate the state transitions. If the resulting state does not match the client’s reported state, a StateMismatch error is returned. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID statusName string  ~ 36 chars Status name events List 0 ~ 1000 items List of events timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Status of State Machine Implementation Example deleteStatusByUserId Delete state machine by specifying a user ID Forcefully deletes the state machine status regardless of its current state (Running, Pass, or Error). Unlike Exit, this does not require the state machine to have reached a terminal state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID statusName string  ~ 36 chars Status name timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Stopped state machine Implementation Example exitStateMachine Exit and delete state machine Can only be used when the state of the state machine is “Pass” or “Error”. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token statusName string  ~ 36 chars Status name Result Type Description item Status Exited state machine Implementation Example exitStateMachineByUserId Exit and delete state machine by specifying a user ID Can only be used when the state of the state machine is “Pass” or “Error”. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID statusName string  ~ 36 chars Status name timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item Status Exited state machine Implementation Example describeStateMachineMasters Get a list of State Machine Masters Retrieves a paginated list of state machine master versions. Each version contains a main state machine name and a GS2 Script payload defining the state machine logic. Multiple versions can exist simultaneously, identified by timestamp-based version numbers. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-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 acquired Result Type Description items List List of State Machine Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example updateStateMachineMaster Create or update a new State Machine Master Creates a new version of the state machine master. The payload containing the GS2 Script state machine definition is validated by parsing before saving. A new version is created with a timestamp-based version number each time this API is called, preserving previous versions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mainStateMachineName string  ~ 128 chars Main state machine name The name of the entry-point state machine in the GSL definition. Execution begins from this state machine, which can call sub-state machines via the stack mechanism. payload string  ~ 5242880 chars State machine definition The GSL (GS2 State Language) source code that defines the state machine’s states, transitions, and actions. Stored separately from the metadata for efficient retrieval. Result Type Description item StateMachineMaster Created State Machine Master Implementation Example getStateMachineMaster Get State Machine Master Retrieves the specified version of the state machine master including the main state machine name and GS2 Script payload that defines the state machine logic. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). version long  0 ~ 32503680000000 Version The version identifier of this state machine definition. Automatically assigned on creation. Used in combination with lowestStateMachineVersion on the namespace to enforce version compatibility for running instances. Result Type Description item StateMachineMaster State Machine Master Implementation Example deleteStateMachineMaster Delete State Machine Master Deletes the specified version of the state machine master. Running state machines that were started with this version will continue to operate, but new state machines cannot be started with a deleted version. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). version long  0 ~ 32503680000000 Version The version identifier of this state machine definition. Automatically assigned on creation. Used in combination with lowestStateMachineVersion on the namespace to enforce version compatibility for running instances. Result Type Description item StateMachineMaster State Machine Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-StateMachine SDK for various programming languages\n","title":"GS2-StateMachine SDK API Reference","url":"/api_reference/state_machine/sdk/"},{"content":"Models Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing version check operations. assumeUserId string  ~ 1024 chars GS2-Identifier user A unique resource name assigned to all information handled by GS2\" \u003e GRN to be promoted if the version check is passed The GS2-Identifier user whose permissions are assumed when the version check passes. This allows the system to perform authorized actions (such as granting access) on behalf of the user after successful version verification. acceptVersionScript ScriptSetting Script to run when a version is accepted/approved Script Trigger Reference - acceptVersion checkVersionTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to perform version checking process Script Trigger Reference - checkVersion logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to version checks and version approval operations. createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic. Details  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua. Details  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes. Details  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. GitHubCheckoutSetting Setting for checking out master data from GitHub Details  apiKeyId string  ~ 1024 chars GitHub API Key A unique resource name assigned to all information handled by GS2\" \u003e GRN repositoryName string  ~ 1024 chars Repository Name sourcePath string  ~ 1024 chars Master data (JSON) file path referenceType string (enum) enum {   “commit_hash”,   “branch”,   “tag” }  Source of code Definition Description “commit_hash” Commit hash “branch” Branch “tag” Tag commitHash string {referenceType} == “commit_hash”  ~ 1024 chars Commit hash * Required if referenceType is “commit_hash” branchName string {referenceType} == “branch”  ~ 1024 chars Branch Name * Required if referenceType is “branch” tagName string {referenceType} == “tag”  ~ 1024 chars Tag Name * Required if referenceType is “tag” AcceptVersion Approved Version Not a version tied to data, such as an app version or asset version. Used for entities that require version control on a per-user basis, such as a version of an agreed upon Terms of Use. Details  acceptVersionId string * ~ 1024 chars Approved Version A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. userId string  ~ 128 chars User ID version Version  Version The version number that the user has approved or rejected. When used with “active” scope version models, this version is compared against the model’s current version during version checks. status string (enum) enum {   “accept”,   “reject” } “accept” Status The user’s approval decision for this version. “accept” means the user has approved the version (e.g., agreed to terms of service), while “reject” means the user has explicitly declined. Definition Description “accept” Accepted “reject” Rejected createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision VersionModel Version Model You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version. Details  versionModelId string * ~ 1024 chars Version Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Version Model name Version 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Enabled only if scope is “active” Status Version Status Indicates the result of version verification. Contains the version model used for checking and the current version reported by the client or recorded from user approval. Returned as part of version check results to inform the client whether the version is up to date, needs an upgrade warning, or is blocked. Details  versionModel VersionModel  Version Model The version model definition used for this version check. Contains the warning and error version thresholds, scope, and other configuration that determined the check result. currentVersion Version Current Version The version that was evaluated during the version check. For “passive” scope, this is the version declared by the client. For “active” scope, this is the version the user has previously approved. May be absent if no version information is available. TargetVersion Version to be verified Represents a version declaration submitted by the client for version checking. In unsigned mode, the version is specified directly. In signed mode, the version is embedded in the body along with a cryptographic signature to prevent tampering. Details  versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). body string ~ 1048576 chars Body The signed payload containing the version information. Used when signature verification is enabled (needSignature is true). The body contains the version data in a format that can be verified against the signature. signature string ~ 256 chars Signature The cryptographic signature for verifying the body content. When provided, the server validates the signature using the GS2-Key encryption key configured in the version model before accepting the declared version. version Version {signature} == \"\"  Version The version number to be verified. Used when signature verification is not required (no signature provided). When a signature is provided, the version is extracted from the signed body instead. * Required if signature is “\" SignTargetVersion Sign Target Version The data structure used as the signing target for version declarations. Contains region, owner, namespace, version model name, and the version number. This data is signed with a GS2-Key encryption key to produce a tamper-proof version declaration that the client submits for version checking. Details  region string  ~ 128 chars Region namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). version Version  Version The version number to be included in the signed payload. This version, along with the namespace and version model context, forms the data that is cryptographically signed. Version Version Represents a version number with a three-level hierarchy (major, minor, micro). Version comparison is performed hierarchically: major version is compared first, then minor, then micro. Used to define warning and error thresholds for version checking. Details  major int  0 ~ 2147483646 Major version The highest priority component in version comparison. A difference in major version takes precedence over minor and micro versions. minor int  0 ~ 2147483646 Minor version The second priority component in version comparison. Compared only when the major versions are equal. micro int  0 ~ 2147483646 Micro version The lowest priority component in version comparison. Compared only when both major and minor versions are equal. ScheduleVersion Version that switches in chronological order Defines a set of version thresholds (current, warning, error) that become active during a specific time period controlled by a GS2-Schedule event. Multiple schedule versions can be configured to implement gradual version enforcement, such as warning users before blocking outdated clients. Details  currentVersion Version  Current Version The latest version available during this schedule period. Used with “active” scope to inform users of the current version when approving updates. warningVersion Version  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification during this schedule period. Login is allowed but the user is prompted to upgrade. errorVersion Version  Version that is determined to be an error by the version check The minimum version threshold for allowing login during this schedule period. If the client’s version is below this value, the version check results in an error and login is blocked. scheduleEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that enables version check Specifies the GS2-Schedule event that controls when this set of version thresholds is active. The version check configuration defined here only applies during the period when the specified event is active. CurrentVersionMaster Currently active Version Model master data This master data defines the Version Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Version Master Data Reference for the JSON file format. Details  namespaceId string * ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server settings string  ~ 5242880 bytes (5MB) Master Data VersionModelMaster Version Model Master Version Model Master is data used to edit and manage Version Model within the game. It is temporarily stored in the Management Console’s Master Data Editor. By performing import and update processes, it is reflected as Version Model actually referenced by the game. For version models, you can configure a warning version that accepts logins but notifies users that an upgrade is available, and an error version that does not accept logins. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version. Details  versionModelId string * ~ 1024 chars Version Model Master A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Enabled only if scope is “active” createdAt long * Current time Creation Timestamp Unix time, milliseconds * Set automatically by the server updatedAt long * Current time Last Updated Timestamp Unix time, milliseconds * Set automatically by the server revision long 0 0 ~ 9223372036854775805 Revision Methods describeNamespaces Get a list of Namespaces Retrieves a list of namespaces that have been created on a per-service basis within the project. You can use the optional page token to start acquiring data from a specific location in the list. You can also limit the number of namespaces to be acquired. Details Request  namePrefix string ~ 64 chars Filter by Namespace name prefix 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 List of Namespaces nextPageToken string Page token to retrieve the rest of the listing Implementation Example createNamespace Create a new Namespace You must specify detailed information including the name, description, and various settings of the namespace. Details Request  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing version check operations. assumeUserId string  ~ 1024 chars GS2-Identifier user A unique resource name assigned to all information handled by GS2\" \u003e GRN to be promoted if the version check is passed acceptVersionScript ScriptSetting Script to run when a version is accepted/approved Script Trigger Reference - acceptVersion checkVersionTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to perform version checking process logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to version checks and version approval operations. Result Type Description item Namespace Namespace created Implementation Example getNamespaceStatus Get Namespace status Get the current status of the specified namespace. This includes whether the Namespace is active, pending, or in some other state. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description status string Implementation Example getNamespace Get a Namespace Get detailed information about the specified namespace. This includes the name, description, and other settings of the namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace Namespace Implementation Example updateNamespace Update Namespace Update the settings of the specified Namespace. You can change the description and other settings of the Namespace. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing version check operations. assumeUserId string  ~ 1024 chars GS2-Identifier user A unique resource name assigned to all information handled by GS2\" \u003e GRN to be promoted if the version check is passed acceptVersionScript ScriptSetting Script to run when a version is accepted/approved Script Trigger Reference - acceptVersion checkVersionTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to perform version checking process logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to version checks and version approval operations. Result Type Description item Namespace Namespace updated Implementation Example deleteNamespace Delete Namespace Delete the specified Namespace. This operation is irreversible and all data associated with the deleted Namespace will be lost. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item Namespace The deleted Namespace Implementation Example getServiceVersion Get the microservice version Details Request Request parameters: None Result Type Description item string Version Implementation Example dumpUserDataByUserId Dump data associated with the specified user ID Can be used to meet legal requirements for the protection of personal information, or to back up or migrate data. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkDumpUserDataByUserId Check if the dump of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of output data Implementation Example cleanUserDataByUserId Delete user data Execute cleaning of data associated with the specified user ID This allows you to safely delete specific user data from the project. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkCleanUserDataByUserId Check if the clean of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example prepareImportUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. You can start the actual import process by uploading the exported zip file to the URL returned in the return value of this API and calling importUserDataByUserId. Details Request  userId string  ~ 128 chars User ID timeOffsetToken string ~ 1024 chars Time offset token Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload user data Implementation Example importUserDataByUserId Execute import of data associated with the specified user ID The data that can be used for import is limited to the data exported by GS2, and old data may fail to import. You can import data with a user ID different from the one you exported, but if the user ID is included in the payload of the user data, this may not be the case. Before calling this API, you must call prepareImportUserDataByUserId to complete the upload preparation. Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description Implementation Example checkImportUserDataByUserId Check if the import of the data associated with the specified user ID is complete Details Request  userId string  ~ 128 chars User ID uploadToken string  ~ 1024 chars Token received in preparation for upload timeOffsetToken string ~ 1024 chars Time offset token Result Type Description url string URL of log data Implementation Example describeAcceptVersions Get a list of Approved Versions Retrieves a paginated list of versions that the requesting user has approved or rejected. Each record contains the version model name and the version number that was accepted/rejected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token 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 List of Approved Versions nextPageToken string Page token to retrieve the rest of the listing Implementation Example describeAcceptVersionsByUserId Get a list of Approved Versions by specifying a user ID Retrieves a paginated list of versions that the specified user has approved or rejected. Each record contains the version model name and the version number that was accepted/rejected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID 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 timeOffsetToken string ~ 1024 chars Time offset token Result Type Description items List List of Approved Versions nextPageToken string Page token to retrieve the rest of the listing Implementation Example accept Approve current version When using this function in terms of service, if the server’s current version is updated while the user is confirming the terms of service, an error will occur. Therefore, please specify the version you are trying to agree to in the version argument. If you do not specify a version, the approval will be made with the latest version, and if there is an argument version specified and that version meets the error version condition, an error will occur. Even if the conditions other than the error version are met, the API will succeed and the client will be considered to have approved the version specified by the client. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. accessToken string  ~ 128 chars Access token version Version Approved Version Result Type Description item AcceptVersion Approved Version Implementation Example acceptByUserId Approve current version by specifying a user ID When using this function in terms of service, if the server’s current version is updated while the user is confirming the terms of service, an error will occur. Therefore, please specify the version you are trying to agree to in the version argument. If you do not specify a version, the approval will be made with the latest version, and if there is an argument version specified and that version meets the error version condition, an error will occur. Even if the conditions other than the error version are met, the API will succeed and the client will be considered to have approved the version specified by the client. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. userId string  ~ 128 chars User ID version Version Approved Version timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item AcceptVersion Approved Version Implementation Example reject Reject current version Used to record that the current version has been rejected in terms of service that do not require approval. The VersionModel’s approveRequirement must be optional to call this API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. accessToken string  ~ 128 chars Access token version Version Rejected Version Result Type Description item AcceptVersion Rejected Version Implementation Example rejectByUserId Reject current version by specifying a user ID Used to record that the current version has been rejected in terms of service that do not require approval. The VersionModel’s approveRequirement must be optional to call this API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. userId string  ~ 128 chars User ID version Version Rejected Version timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item AcceptVersion Rejected Version Implementation Example getAcceptVersion Get Approved Version Retrieves the version approval record for the requesting user and the specified version model, including the version number that was accepted or rejected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. Result Type Description item AcceptVersion Approved Version Implementation Example getAcceptVersionByUserId Get Approved Version by specifying a user ID Retrieves the version approval record for the specified user and version model, including the version number that was accepted or rejected. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item AcceptVersion Approved Version Implementation Example deleteAcceptVersion Delete Approved Version Deletes the version approval record for the requesting user. After deletion, the user will need to re-approve the version on the next version check if the version model uses active scope. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. Result Type Description item AcceptVersion Approved Version deleted Implementation Example deleteAcceptVersionByUserId Delete Approved Version by specifying a user ID Deletes the version approval record for the specified user. After deletion, the user will need to re-approve the version on the next version check if the version model uses active scope. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID versionName string  ~ 128 chars Version Name The name of the version model that this approval record is associated with. Links the user’s approval to a specific version model definition. timeOffsetToken string ~ 1024 chars Time offset token Result Type Description item AcceptVersion Approved Version deleted Implementation Example checkVersion Check Version Checks the client’s versions against all version models in the namespace. For passive scope models, the client-reported version from targetVersions is used (with optional signature verification via the key service). For active scope models, the user’s previously accepted version is looked up. Returns separate lists of warnings and errors based on version thresholds. If all checks pass with no errors, a project token is issued by assuming the namespace’s configured user identity. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). accessToken string  ~ 128 chars Access token targetVersions List [] 0 ~ 1000 items List of Versions to be verified Result Type Description projectToken string Signed in to the project token. warnings List Version Verification Results List of Warnings errors List Version Verification Results List of errors Implementation Example checkVersionByUserId Check Version by specifying a user ID Checks the specified user’s versions against all version models in the namespace. For passive scope models, the client-reported version from targetVersions is used (with optional signature verification). For active scope models, the user’s previously accepted version is looked up. Returns separate lists of warnings and errors based on version thresholds. If all checks pass with no errors, a project token is issued. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID targetVersions List [] 0 ~ 1000 items List of Versions to be verified timeOffsetToken string ~ 1024 chars Time offset token Result Type Description projectToken string Signed in to the project token. warnings List Version Verification Results List of Warnings errors List Version Verification Results List of errors Implementation Example calculateSignature Calculate version signature Calculates a cryptographic signature for the specified version using the key service. The version information along with region, owner, and namespace context is serialized into a body and signed using the signature key configured on the version model. The resulting body and signature can be used for signature-verified version checks in passive scope models. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). version Version Version Result Type Description body string Body signature string Signature Implementation Example describeVersionModels Get a list of Version Models Retrieves the list of currently active version models. Each model defines version check rules including scope (passive/active), warning/error version thresholds, schedule-based version controls, and signature verification settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description items List List of Version Models Implementation Example getVersionModel Get Version Model Retrieves the specified version model including its scope, warning/error version thresholds, schedule-based version rules, signature requirement, and approval settings. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item VersionModel Version Model Implementation Example exportMaster Export Version Model Master in a master data format that can be activated Exports the currently registered version model masters in an activatable master data format. The exported data contains all version model definitions including scope, version thresholds, schedule rules, signature settings, and approval requirements. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentVersionMaster Version Model master data that can be activated Implementation Example getCurrentVersionMaster Get currently active Version Model master data Retrieves the currently active version model master data that is being used for version checks, including all version model definitions. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item CurrentVersionMaster Currently active Version Model master data Implementation Example preUpdateCurrentVersionMaster Update currently active Version Model master data (3-phase version) When uploading master data larger than 1MB, the update is performed in 3 phases. Execute this API to obtain a token and URL for uploading. Upload the master data to the obtained URL. Execute UpdateCurrentModelMaster by passing the token obtained from the the upload to reflect the master data. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description uploadToken string Token used to reflect results after upload uploadUrl string URL used to upload Implementation Example updateCurrentVersionMaster Update currently active Version Model master data Updates the currently active version model master data. Supports both direct update mode and pre-upload mode for handling large master data. In pre-upload mode, the settings are read using the upload token obtained from the PreUpdate API. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” Result Type Description item CurrentVersionMaster Updated master data of the currently active Version Models Implementation Example updateCurrentVersionMasterFromGitHub Update currently active Version Model master data from GitHub Updates the currently active version model master data by checking out master data from a GitHub repository using the specified checkout settings. The API key is decrypted via the key service to authenticate with GitHub. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). checkoutSetting GitHubCheckoutSetting  Setting for checking out master data from GitHub Result Type Description item CurrentVersionMaster Updated master data of the currently active Version Models Implementation Example describeVersionModelMasters Get a list of Version Model Masters Retrieves a paginated list of version model masters. Can filter by name prefix. Each master defines version check rules including scope (passive/active), warning/error version thresholds, schedule-based version controls, signature verification settings, and approval requirements. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). namePrefix string ~ 64 chars Filter by version name prefix 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 List of Version Model Masters nextPageToken string Page token to retrieve the rest of the listing Implementation Example createVersionModelMaster Create a new Version Model Master Creates a new version model master with scope (passive: client-reported version, active: server-managed approval), current/warning/error version thresholds, optional schedule-based version rules, signature verification settings, and approval requirement (required/optional). Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Required if scope is “active” Result Type Description item VersionModelMaster Version Model Master created Implementation Example getVersionModelMaster Get Version Model Master Retrieves the specified version model master including its scope, version thresholds, schedule-based rules, signature settings, and approval requirements. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item VersionModelMaster Version Model Master Implementation Example updateVersionModelMaster Update Version Model Master Updates the specified version model master’s scope, version thresholds, schedule-based rules, signature settings, and approval requirements. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Required if scope is “active” Result Type Description item VersionModelMaster Version Model Master updated Implementation Example deleteVersionModelMaster Delete Version Model Master Deletes the specified version model master. This only removes the master definition and does not affect the currently active version configuration. Details Request  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). versionName string  ~ 128 chars Version Model name Version Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). Result Type Description item VersionModelMaster Version Model Master deleted Implementation Example","lang":"en","section":"api_reference","summary":"Specification of models and API references for GS2-Version SDK for various programming languages\n","title":"GS2-Version SDK API Reference","url":"/api_reference/version/sdk/"},{"content":"GS2-Deploy did a great job of setting up the environment. However, there was still a challenge in writing templates. That is, you cannot get any input help to write a template file. I have already explained that I used AWS’ Cloud Formation as a reference to design GS2-Deploy, but In 2019, AWS announced the AWS CDK (Cloud Development Kit). This was the result of an effort to enable template writing in various programming languages, as a solution to the problem of not getting input support for writing template files in traditional JSON or YAML. Since its launch in 2019, GS2 has always provided the ability to deploy templates in JSON/YAML, and in November 2022, GS2 began supporting CDK as well. CDK currently supports Go / Java / PHP / Python / TypeScript. Below is an example of code written in each of these programming languages to generate a template for GS2-Inventory’s GS2-Deploy. If the generated template files are linked to the point where they are reflected as master data using GS2-SDK, GS2 resource maintenance can be done entirely in the programming language.","lang":"en","section":"overview","summary":"Create GS2-Deploy template using GS2-CDK\n","title":"Setup using GS2-CDK","url":"/overview/workflow/setup_gs2_resources/cdk_setup/"},{"content":"Basic Support Basic support is available for free. You can ask questions through the forum . While GS2 staff may answer questions, mutual assistance among users is the main expectation. We provide as much support as possible, but we may not be able to respond to individual inquiries about specific project circumstances. If you have a question about a code issue, please provide the code for a program that can be reproduced. Business Support Business support is available for a monthly fee of 3,000 USD. If you are considering adopting GS2 for multiple projects within the same company, a support contract is required for each project. You can communicate privately using your preferred messenger. We provide guidance on designing GS2 based on your project plan. Support includes answering questions related to GS2, reporting and fixing bugs, and providing advice on how to utilize each GS2 microservice based on your project plan. We provide up to 15 hours of support per month. Additional charges may apply if support exceeds this limit. Professional Service Professional services are available for 200 USD per hour. A Business Support contract is required. We offer advanced support for issues that are not covered by Business Support. This includes implementation assistance for specific features, advice on security settings, code review, and log analysis. Each support session lasts for a minimum of one hour and multiple sessions can be used. However, if a support session is expected to last for a long time, prior consultation is required. Professional Service requires a minimum of one hour of usage per session and requires a developer with a basic understanding of GS2 API usage. Please contact us via chat for more information. Prototyping During the initial prototyping phase of game development, Business Support + GS2 usage fees can be used for a monthly fee of 1,000 USD. Prototyping includes the following support: Equivalent to Business Support GS2 usage fees Prototyping can be used for a maximum of three months. Please contact us via chat for more information.","lang":"en","section":"pricing","summary":"Support menu for leveraging Game Server Services.\n","title":"support menu","url":"/pricing/support/"},{"content":"Here","lang":"en","section":"get_start","summary":"Introduction of GS2 UIKit for Unity implementation samples","title":"Sample implementation of GS2 UIKit for Unity","url":"/get_start/uikit/sample/"},{"content":"GS2-SDK is a game engine-specific SDK. Developers using Unity and Unreal Engine 5 can take advantage of the various features provided by this SDK. Unity “GS2-SDK for Unity” is available as an SDK for Unity. It is fully integrated with the Unity Package Manager (UPM) and SDK updates can be done through UPM. Dependent libraries are LitJSON (Public Domain) / websocket-sharp (MIT) / Protocol Buffers (BSD). The GS2-SDK for Unity is available under Apache License 2.0 and all source code is available in the following GitHub repository https://github.com/gs2io/gs2-csharp-sdk https://github.com/gs2io/gs2-sdk-for-unity https://github.com/gs2io/gs2-uikit-for-unity The GS2-SDK for Unity provides state management capabilities for data retrieved from the server. Data retrieved through the API is cached in a layer of the SDK, and when server values are updated, the cache is automatically updated as well. Therefore, developers can call the GS2-SDK API from the Update function to access the latest values without having to think about reading data. Example Implementation var result = await gs2.Account.Namespace( namespaceName: \"namespace-0001\" ).CreateAsync(); var item = await result.ModelAsync(); var userId = item.UserId; var password = item.Password; GS2-UIKit for Unity This is a more Unity-specific SDK. By simply adding a component to a GameObject in the Unity editor, you can add a component to the text of the GameObject to reflect the number of items it has. You can enable or disable GameObjects depending on whether or not the limit has been reached. If the implementation is as simple as retrieving data from the server and displaying it in the UI, the UI Kit can be used to accomplish this without any code. Unreal Engine 5 GS2-SDK for Unreal Engine is available as an SDK for Unreal Engine 5. It is provided as a plugin for Unreal Engine and can be integrated into your project by simply placing code. There are no external libraries to depend on and everything is implemented using standard Unreal Engine 5 functionality. GS2-SDK for Unreal Engine is licensed under Apache License 2.0 and all source code is available in the following GitHub repository https://github.com/gs2io/gs2-sdk-for-ue5 Example Implementation const auto Domain = Gs2-\u003eAccount-\u003eNamespace( \"namespace-0001\" // namespaceName ); const auto Future = Domain-\u003eCreate( ); Future-\u003eStartSynchronousTask(); if (Future-\u003eGetTask().IsError()) return false; // obtain changed values / result values const auto Future2 = Future-\u003eGetTask().Result()-\u003eModel(); Future2-\u003eStartSynchronousTask(); if (!TestFalse(WHAT, Future2-\u003eGetTask().IsError()))) return false; const auto Result = Future2-\u003eGetTask().Result(); Blueprint SDK This SDK is more specific to Unreal Engine 5. This SDK supports Blueprint, a node-based programming environment that can be developed in the Unreal Editor. The Blueprint SDK allows you to access GS2 functionality without having to use C++.","lang":"en","section":"overview","summary":"Game Development with GS2\n","title":"Implementation","url":"/overview/workflow/coding/"},{"content":"To start using the GS2-Account service, you need to add a namespace. Namespace (namespace) is a mechanism to allow the same service to be used for different purposes within a single project. Within different namespaces, the same service is treated as a completely different data space. Now, using the sample template, add game-0001 to the GS2-Account namespace name and issue the encryption key that will be used to authenticate the account and make it possible to create a new account. Create resources with GS2-Deploy GS2-Deploy is a service for collectively creating and managing resources for multiple services based on template files (YAML format). Log in to the Management Console . Select Deploy from the left menu and click Stacks . Click Create new stack . Enter an arbitrary name such as initialize-account in Stack name . Copy and paste the following template content into the Template data field. Click the Create button. It will take a few seconds to several tens of seconds to complete. It is complete when the status becomes CREATE_COMPLETE . Download sample template","lang":"en","section":"get_start","summary":"Prepare resources for issuing anonymous accounts and logging in\n","title":"Prepare resources needed for login processing","url":"/get_start/tutorial/setup_account/"},{"content":"Trigger createAccount Account creation Synchronous Execution Script The script is executed synchronously before the account creation process. Request Type Description namespace Namespace Namespace account Account Game Player Account Result Type Required Default Value Limits Description permit bool  Whether to allow account creation Implementation Example Asynchronous Execution Script The script is executed asynchronously after the account creation process. Request Type Description namespace Namespace Namespace account Account Game Player Account Implementation Example authentication Account authentication Synchronous Execution Script The script is executed synchronously before the account authentication process. Request Type Description namespace Namespace Namespace account Account Game Player Account elapsedHours int Elapsed time since last login Result Type Required Default Value Limits Description permit bool  Whether to allow account authentication force bool false Whether to allow authentication even if password authentication fails Implementation Example Asynchronous Execution Script The script is executed asynchronously after the account authentication process. Request Type Description namespace Namespace Namespace account Account Game Player Account elapsedHours int Elapsed time since last login Implementation Example ban Account Ban registration Synchronous Execution Script The script is executed synchronously before the account ban registration process. Request Type Description namespace Namespace Namespace account Account Game Player Account addBanStatus BanStatus Account Ban Status to be added Result Type Required Default Value Limits Description permit bool  Whether to allow Account Ban registration Implementation Example Asynchronous Execution Script The script is executed asynchronously after the account ban registration process. Request Type Description namespace Namespace Namespace account Account Game Player Account addBanStatus BanStatus Account Ban Status to add Implementation Example unBan Account Ban removal Synchronous Execution Script The script is executed synchronously before the account ban removal process. Request Type Description namespace Namespace Namespace account Account Game Player Account Result Type Required Default Value Limits Description permit bool  Whether to allow Account Ban removal Implementation Example Asynchronous Execution Script The script is executed asynchronously after the account ban removal process. Request Type Description namespace Namespace Namespace account Account Game Player Account Implementation Example createTakeOver Registration of TakeOver Information Synchronous Execution Script The script is executed synchronously before the registration of takeover information process. Request Type Description namespace Namespace Namespace takeOver TakeOver TakeOver Information account Account Game Player Account Result Type Required Default Value Limits Description permit bool  Whether to allow registration of TakeOver Information Implementation Example Asynchronous Execution Script The script is executed asynchronously after the registration of takeover information process. Request Type Description namespace Namespace Namespace takeOver TakeOver TakeOver Information account Account Game Player Account Implementation Example doTakeOver TakeOver execution Synchronous Execution Script The script is executed synchronously before the takeover execution process. Request Type Description namespace Namespace Namespace account Account Game Player Account takeOver TakeOver TakeOver Information Result Type Required Default Value Limits Description permit bool  Whether to allow takeover execution force bool false Whether to allow authentication even if password authentication fails Implementation Example Asynchronous Execution Script The script is executed asynchronously after the takeover execution process. Request Type Description namespace Namespace Namespace account Account Game Player Account takeOver TakeOver TakeOver Information Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Account Script Trigger Reference","url":"/api_reference/account/script/"},{"content":"Trigger acquirePoint Point acquisition Synchronous Execution Script The script is executed synchronously before the point acquisition process. Request Type Description namespace Namespace Namespace point Point Point before acquisition processing acquirePointValue long Amount of points to be acquired Result Type Required Default Value Limits Description permit bool  Whether to allow point acquisition overridePointValue long 0 ~ 2147483645 Amount of points to override the acquisition value Implementation Example Asynchronous Execution Script The script is executed asynchronously after the point acquisition process. Request Type Description namespace Namespace Namespace point Point Point before acquisition processing afterPoint Point Point after acquisition processing acquirePointValue long Amount of points to be acquired Implementation Example consumePoint Point consumption Synchronous Execution Script The script is executed synchronously before the point consumption process. Request Type Description namespace Namespace Namespace point Point Point before consumption processing consumePointValue long Amount of points to be consumed Result Type Required Default Value Limits Description permit bool  Whether to allow point consumption overridePointValue long 0 ~ 2147483645 Amount of points to override the consumption value Implementation Example Asynchronous Execution Script The script is executed asynchronously after the point consumption process. Request Type Description namespace Namespace Namespace point Point Point before consumption processing afterPoint Point Point after consumption processing consumePointValue long Amount of points to be consumed Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-AdReward Script Trigger Reference","url":"/api_reference/ad_reward/script/"},{"content":"Trigger apply Buff application Synchronous Execution Script The script is executed synchronously before the buff application process. Request Type Description namespace Namespace Namespace buffEntryModel BuffEntryModel Buff Entry Model userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow the buff to be applied overrideBuffRate float  0 ~ 100 Override rate applied to the buff (multiplier) Implementation Example Asynchronous Execution Script The script is executed asynchronously after the buff application process. Request Type Description namespace Namespace Namespace buffEntryModel BuffEntryModel Buff Entry Model userId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Buff Script Trigger Reference","url":"/api_reference/buff/script/"},{"content":"Trigger createRoom Room creation Synchronous Execution Script The script is executed synchronously before the room creation process. Request Type Description namespace Namespace Namespace room Room Room Result Type Required Default Value Limits Description permit bool  Whether to allow room creation Implementation Example Asynchronous Execution Script The script is executed asynchronously after the room creation process. Request Type Description namespace Namespace Namespace room Room Room Implementation Example deleteRoom Room deletion Synchronous Execution Script The script is executed synchronously before the room deletion process. Request Type Description namespace Namespace Namespace room Room Room Result Type Required Default Value Limits Description permit bool  Whether to allow room deletion Implementation Example Asynchronous Execution Script The script is executed asynchronously after the room deletion process. Request Type Description namespace Namespace Namespace room Room Room Implementation Example postMessage Message posting Synchronous Execution Script The script is executed synchronously before the message posting process. Request Type Description namespace Namespace Namespace room Room Room message Message Message Result Type Required Default Value Limits Description permit bool  Whether to allow message posting Implementation Example Asynchronous Execution Script The script is executed asynchronously after the message posting process. Request Type Description namespace Namespace Namespace room Room Room message Message Message Implementation Example subscribeRoom Room subscription Synchronous Execution Script The script is executed synchronously before the room subscription process. Request Type Description namespace Namespace Namespace room Room Room subscribe Subscribe Subscribe Result Type Required Default Value Limits Description permit bool  Whether to allow room subscription Implementation Example Asynchronous Execution Script The script is executed asynchronously after the room subscription process. Request Type Description namespace Namespace Namespace room Room Room subscribe Subscribe Subscribe Implementation Example unsubscribeRoom Room unsubscription Synchronous Execution Script The script is executed synchronously before the room unsubscription process. Request Type Description namespace Namespace Namespace room Room Room subscribe Subscribe Subscribe Result Type Required Default Value Limits Description permit bool  Whether to allow room unsubscription Implementation Example Asynchronous Execution Script The script is executed asynchronously after the room unsubscription process. Request Type Description namespace Namespace Namespace room Room Room subscribe Subscribe Subscribe Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Chat Script Trigger Reference","url":"/api_reference/chat/script/"},{"content":"Trigger doneUpload Report completion of data object upload Synchronous Execution Script The script is executed synchronously before the report completion of data object upload process. Request Type Description namespace Namespace Namespace dataObject DataObject Data object objectUrl string URL of the uploaded object Result Type Required Default Value Limits Description permit bool  Whether to allow report completion of data object upload Implementation Example Asynchronous Execution Script The script is executed asynchronously after the report completion of data object upload process. Request Type Description namespace Namespace Namespace dataObject DataObject Data object Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Datastore Script Trigger Reference","url":"/api_reference/datastore/script/"},{"content":"Trigger entry entry registration Synchronous Execution Script The script is executed synchronously before the entry registration process. Request Type Description namespace Namespace Namespace entryModels EntryModel[] List of Entry Models userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow entry registration Implementation Example Asynchronous Execution Script The script is executed asynchronously after the entry registration process. Request Type Description namespace Namespace Namespace entryModels EntryModel[] List of Entry Models userId string User ID Implementation Example duplicateEntry re-registration for entries already registered Synchronous Execution Script The script is executed synchronously before the re-registration for entries already registered process. Request Type Description namespace Namespace Namespace entryModel EntryModel Entry Model userId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Dictionary Script Trigger Reference","url":"/api_reference/dictionary/script/"},{"content":"Trigger enhance enhancement execution Synchronous Execution Script The script is executed synchronously before the enhancement execution process. Request Type Description namespace Namespace Namespace rateModel RateModel Enhanced Rate Model targetItemSetId string GRN for the enhanced Item Set bonusRate float Experience bonus multiplier (1.0 = no bonus) experienceValue long Amount of experience gained Result Type Required Default Value Limits Description permit bool  Whether to allow enhancement execution overrideExperienceValue long 0 ~ 2147483645 Amount of gained experience to override Implementation Example Asynchronous Execution Script The script is executed asynchronously after the enhancement execution process. Request Type Description namespace Namespace Namespace rateModel RateModel Enhanced Rate Model targetItemSetId string GRN for the enhanced Item Set bonusRate float Experience bonus multiplier (1.0 = no bonus) experienceValue long Amount of experience gained Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Enhance Script Trigger Reference","url":"/api_reference/enhance/script/"},{"content":"Trigger exchange Exchange Synchronous Execution Script The script is executed synchronously before the exchange process. Request Type Description namespace Namespace Namespace rateModel RateModel Exchange Rate Model userId string User ID performing the exchange count int Exchanging volume config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow exchange rateMode string  “float” Rate mode rate float 1.0 0 ~ 1000 Acquisition quantity rate logRate LogRate Logarithmic acquisition correction Implementation Example Asynchronous Execution Script The script is executed asynchronously after the exchange process. Request Type Description namespace Namespace Namespace rateModel RateModel Exchange Rate Model userId string User ID performing the exchange count int Exchanging volume config Config[] Configuration values applied to transaction variables Implementation Example incrementalExchange Exchange Synchronous Execution Script The script is executed synchronously before the exchange process. Request Type Description namespace Namespace Namespace rateModel IncrementalRateModel Exchange rate model userId string User ID performing the exchange count int Exchanging volume config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow exchange Implementation Example Asynchronous Execution Script The script is executed asynchronously after the exchange process. Request Type Description namespace Namespace Namespace rateModel IncrementalRateModel Exchange rate model userId string User ID performing the exchange count int Exchanging volume config Config[] Configuration values applied to transaction variables Implementation Example calculateCost Cost calculation script for Incremental Cost Exchange Rate Synchronous Execution Script The script is executed synchronously before the cost calculation script for incremental cost exchange rate process. Request Type Description namespace Namespace Namespace incrementalRateModel IncrementalRateModel Incremental Cost Exchange Rate Model userId string User ID currentExchangeCount int Current number of exchange counts quantity int Exchange Quantity Result Type Required Default Value Limits Description costMode string  “num” Cost calculation method cost long 0 ~ 9223372036854775805 Cost logCost LogCost Cost calculation result using logarithm Implementation Example acquireAwait Exchange Await Synchronous Execution Script The script is executed synchronously before the exchange await process. Request Type Description namespace Namespace Namespace rateModel RateModel Exchange Rate Model awaitModel Await Exchange Await Result Type Required Default Value Limits Description permit bool  Whether to allow awaiting exchange Implementation Example Asynchronous Execution Script The script is executed asynchronously after the exchange await process. Request Type Description namespace Namespace Namespace rateModel RateModel Exchange Rate Model awaitModel Await Exchange Await Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Exchange Script Trigger Reference","url":"/api_reference/exchange/script/"},{"content":"Trigger rankCapScript obtaining rank caps Synchronous Execution Script The script is executed synchronously before the obtaining rank caps process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model userId string User ID propertyId string Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. Result Type Required Default Value Limits Description rankCap long  0 ~ 2147483645 rank cap Implementation Example changeExperience experience value changes Synchronous Execution Script The script is executed synchronously before the experience value changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model status Status Status before change afterStatus Status Status after change Result Type Required Default Value Limits Description permit bool  Whether to allow experience value changes overrideExperienceValue long  0 ~ 2147483645 Overriding experience value Implementation Example Asynchronous Execution Script The script is executed asynchronously after the experience value changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model oldStatus Status Status before change status Status Status Implementation Example changeRank rank changes Synchronous Execution Script The script is executed synchronously before the rank changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model status Status Status before change afterStatus Status Status after change Result Type Required Default Value Limits Description permit bool  Whether to allow rank changes Implementation Example Asynchronous Execution Script The script is executed asynchronously after the rank changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model oldStatus Status Status before change status Status Status Implementation Example changeRankCap Rank cap changes Synchronous Execution Script The script is executed synchronously before the rank cap changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model status Status Status before change afterStatus Status Status after change Result Type Required Default Value Limits Description permit bool  Whether to allow rank cap change overrideRankCapValue long  0 ~ 2147483645 New rank cap Implementation Example Asynchronous Execution Script The script is executed asynchronously after the rank cap changes process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model status Status Status Implementation Example overflowExperience Experience overflow Synchronous Execution Script The script is executed synchronously before the experience overflow process. Request Type Description namespace Namespace Namespace experienceModel ExperienceModel Experience Model status Status Status overflowExperienceValue long Experience overflow value Result Type Required Default Value Limits Description permit bool  Whether to allow experience overflow Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Experience Script Trigger Reference","url":"/api_reference/experience/script/"},{"content":"Trigger updateMold Form Storage Area capacity update Synchronous Execution Script The script is executed synchronously before the form storage area capacity update process. Request Type Description namespace Namespace Namespace mold Mold Form Storage Area before update afterMold Mold Form Storage Area after update Result Type Required Default Value Limits Description permit bool  Whether to allow Form Storage Area capacity update Implementation Example Asynchronous Execution Script The script is executed asynchronously after the form storage area capacity update process. Request Type Description namespace Namespace Namespace mold Mold Form Storage Area Implementation Example updateForm Form update Synchronous Execution Script The script is executed synchronously before the form update process. Request Type Description namespace Namespace Namespace mold Mold Form Storage Area form Form Form before update afterForm Form Form after update Result Type Required Default Value Limits Description permit bool  Whether to allow form update Implementation Example Asynchronous Execution Script The script is executed asynchronously after the form update process. Request Type Description namespace Namespace Namespace mold Mold Form Storage Area form Form Form Implementation Example updatePropertyForm Property Form update Synchronous Execution Script The script is executed synchronously before the property form update process. Request Type Description namespace Namespace Namespace propertyForm PropertyForm PropertyForm before update afterPropertyForm PropertyForm PropertyForm after update Result Type Required Default Value Limits Description permit bool  Whether to allow Property Form update Implementation Example Asynchronous Execution Script The script is executed asynchronously after the property form update process. Request Type Description namespace Namespace Namespace propertyForm PropertyForm PropertyForm Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Formation Script Trigger Reference","url":"/api_reference/formation/script/"},{"content":"Trigger updateProfile Update profile Synchronous Execution Script The script is executed synchronously before the update profile process. Request Type Description namespace Namespace Namespace profile Profile Profile oldProfile Profile Old profile publicProfile string New Public profile followerProfile string New profile for followers friendProfile string New profile for friends Result Type Required Default Value Limits Description permit bool  Whether to allow update profile Implementation Example Asynchronous Execution Script The script is executed asynchronously after the update profile process. Request Type Description namespace Namespace Namespace oldProfile Profile Profile before update profile Profile Profile after update Implementation Example follow Follow Synchronous Execution Script The script is executed synchronously before the follow process. Request Type Description namespace Namespace Namespace followUser FollowUser Follow Information Result Type Required Default Value Limits Description permit bool  Whether to allow the follow operation Implementation Example Asynchronous Execution Script The script is executed asynchronously after the follow process. Request Type Description namespace Namespace Namespace followUser FollowUser Follow Information Implementation Example unfollow Unfollow Synchronous Execution Script The script is executed synchronously before the unfollow process. Request Type Description namespace Namespace Namespace followUser FollowUser Follow Information Result Type Required Default Value Limits Description permit bool  Whether to allow the unfollow operation Implementation Example Asynchronous Execution Script The script is executed asynchronously after the unfollow process. Request Type Description namespace Namespace Namespace followUser FollowUser Follow Information Implementation Example deleteFriend Delete friend Synchronous Execution Script The script is executed synchronously before the delete friend process. Request Type Description namespace Namespace Namespace userId string User ID friendUser FriendUser Friend Result Type Required Default Value Limits Description permit bool  Whether to allow deleting a friend Implementation Example Asynchronous Execution Script The script is executed asynchronously after the delete friend process. Request Type Description namespace Namespace Namespace userId string User ID friendUser FriendUser Friend Implementation Example sendRequest Send Friend Request Synchronous Execution Script The script is executed synchronously before the send friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Result Type Required Default Value Limits Description permit bool  Whether to allow send friend request Implementation Example Asynchronous Execution Script The script is executed asynchronously after the send friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Implementation Example cancelRequest Cancel Friend Request Synchronous Execution Script The script is executed synchronously before the cancel friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Result Type Required Default Value Limits Description permit bool  Whether to allow cancellation of friend request Implementation Example Asynchronous Execution Script The script is executed asynchronously after the cancel friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Implementation Example acceptRequest Accept Friend Request Synchronous Execution Script The script is executed synchronously before the accept friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Result Type Required Default Value Limits Description permit bool  Whether to allow accepting the friend request Implementation Example Asynchronous Execution Script The script is executed asynchronously after the accept friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Implementation Example rejectRequest Reject Friend Request Synchronous Execution Script The script is executed synchronously before the reject friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Result Type Required Default Value Limits Description permit bool  Whether to allow rejecting the friend request Implementation Example Asynchronous Execution Script The script is executed asynchronously after the reject friend request process. Request Type Description namespace Namespace Namespace friendRequest FriendRequest Friend Request Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Friend Script Trigger Reference","url":"/api_reference/friend/script/"},{"content":"Trigger changeGrade grade changes Synchronous Execution Script The script is executed synchronously before the grade changes process. Request Type Description namespace Namespace Namespace gradeModel GradeModel Grade Model status Status Status before change afterStatus Status Status after change Result Type Required Default Value Limits Description permit bool  Whether to allow grade changes overrideGradeValue long  0 ~ 2147483645 Overriding grade value Implementation Example Asynchronous Execution Script The script is executed asynchronously after the grade changes process. Request Type Description namespace Namespace Namespace gradeModel GradeModel Grade Model status Status Status afterStatus Status Status after change Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Grade Script Trigger Reference","url":"/api_reference/grade/script/"},{"content":"Trigger createGuild Creating guild Synchronous Execution Script The script is executed synchronously before the creating guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild Result Type Required Default Value Limits Description permit bool  Whether to allow creating guild Implementation Example Asynchronous Execution Script The script is executed asynchronously after the creating guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild Implementation Example updateGuild Update guild Synchronous Execution Script The script is executed synchronously before the update guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model oldGuild Guild Guild before update newGuild Guild Guild after update Result Type Required Default Value Limits Description permit bool  Whether to allow update guild Implementation Example Asynchronous Execution Script The script is executed asynchronously after the update guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model oldGuild Guild Guild before update newGuild Guild Guild after update Implementation Example joinGuild Join guild Synchronous Execution Script The script is executed synchronously before the join guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow join guild Implementation Example Asynchronous Execution Script The script is executed asynchronously after the join guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild userId string User ID Implementation Example leaveGuild Leave guild Synchronous Execution Script The script is executed synchronously before the leave guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild userId string User ID self bool Whether the user left the guild themselves or was removed by the guild master, or if the guild was disbanded Result Type Required Default Value Limits Description permit bool  Whether to allow leave guild Implementation Example Asynchronous Execution Script The script is executed asynchronously after the leave guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild userId string User ID self bool Whether the user left the guild themselves or was removed by the guild master, or if the guild was disbanded Implementation Example changeRole Change role Synchronous Execution Script The script is executed synchronously before the change role process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild oldMembers Member[] Old Member Information newMembers Member[] New Member Information Result Type Required Default Value Limits Description permit bool  Whether to allow change role Implementation Example Asynchronous Execution Script The script is executed asynchronously after the change role process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild oldMembers Member[] Old Member Information newMembers Member[] New Member Information Implementation Example deleteGuild Delete Guild Synchronous Execution Script The script is executed synchronously before the delete guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild Result Type Required Default Value Limits Description permit bool  Whether to allow delete guild Implementation Example Asynchronous Execution Script The script is executed asynchronously after the delete guild process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild Implementation Example receiveJoinRequest Receive join request Synchronous Execution Script The script is executed synchronously before the receive join request process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild receiveMemberRequest ReceiveMemberRequest Join Request Result Type Required Default Value Limits Description permit bool  Whether to allow receive join request Implementation Example Asynchronous Execution Script The script is executed asynchronously after the receive join request process. Request Type Description namespace Namespace Namespace guildModel GuildModel Guild Model guild Guild Guild receiveMemberRequest ReceiveMemberRequest Join Request Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Guild Script Trigger Reference","url":"/api_reference/guild/script/"},{"content":"Trigger receive Receiving rewards Synchronous Execution Script The script is executed synchronously before the receiving rewards process. Request Type Description namespace Namespace Namespace category CategoryModel Category Model userId string User ID executing reward receive status Status Status acquireActions AcquireAction[] Rewards config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow receiving rewards rate float 1.0 0 ~ 1000 Acquisition quantity rate Implementation Example Asynchronous Execution Script The script is executed asynchronously after the receiving rewards process. Request Type Description namespace Namespace Namespace category CategoryModel Category Model userId string User ID executing reward receive oldStatus Status Status before receiving rewards newStatus Status Status after receiving rewards acquireActions AcquireAction[] Rewards config Config[] Configuration values applied to transaction variables Implementation Example overrideAcquireActions Script that dynamically determines the idle reward Acquire Action Synchronous Execution Script After synchronously executing the Script that dynamically determines the idle reward Acquire Action, the Acquire Action is performed. Request Type Description namespace Namespace Namespace categoryModel CategoryModel Category Model userId string User ID Result Type Required Default Value Limits Description acquireActions AcquireActionList[]  1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Idle Script Trigger Reference","url":"/api_reference/idle/script/"},{"content":"Trigger receiveMessage Message reception Synchronous Execution Script The script is executed synchronously before the message reception process. Request Type Description namespace Namespace Namespace message Message Message Result Type Required Default Value Limits Description permit bool  Whether to allow message reception overrideMetadata string 0 ~ 4096 chars Overwritten metadata Implementation Example Asynchronous Execution Script The script is executed asynchronously after the message reception process. Request Type Description namespace Namespace Namespace message Message Message Implementation Example readMessage Message opening Synchronous Execution Script The script is executed synchronously before the message opening process. Request Type Description namespace Namespace Namespace message Message Message Result Type Required Default Value Limits Description permit bool  Whether to allow message opening Implementation Example Asynchronous Execution Script The script is executed asynchronously after the message opening process. Request Type Description namespace Namespace Namespace message Message Message Implementation Example deleteMessage Deleting a message Synchronous Execution Script The script is executed synchronously before the deleting a message process. Request Type Description namespace Namespace Namespace message Message Message Result Type Required Default Value Limits Description permit bool  Whether to allow deleting a message Implementation Example Asynchronous Execution Script The script is executed asynchronously after the deleting a message process. Request Type Description namespace Namespace Namespace message Message Message Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Inbox Script Trigger Reference","url":"/api_reference/inbox/script/"},{"content":"Trigger acquire Item acquisition Synchronous Execution Script The script is executed synchronously before the item acquisition process. Request Type Description namespace Namespace Namespace inventory Inventory Inventory itemSets ItemSet[] List of Item Sets acquireItemName string Name of Item Model acquired userId string User ID acquireCount long Quantity acquired expiresAt long Expiration time Unix time, milliseconds Result Type Required Default Value Limits Description permit bool  Whether to allow item acquisition overrideAcquireCount int 0 ~ 2147483645 Actual amount obtained to be applied Implementation Example Asynchronous Execution Script The script is executed asynchronously after the item acquisition process. Request Type Description namespace Namespace Namespace oldInventory Inventory Inventory before update oldItemSets ItemSet[] List of Item Sets before renewal newInventory Inventory Inventory after update newItemSets ItemSet[] List of updated Item Sets acquireItemName string Name of Item Model acquired userId string User ID acquireCount long Quantity acquired overflowValue long Amount of overflow expiresAt long Expiration time Unix time, milliseconds Implementation Example overflowDone the number of items hits the acquisition limit and notification of the quantity not obtained is completed Synchronous Execution Script The script is executed synchronously before the the number of items hits the acquisition limit and notification of the quantity not obtained is completed process. Request Type Description namespace Namespace Namespace inventory Inventory Inventory itemModel ItemModel Item Model userId string User ID overflowValue long Amount of overflow Implementation Example consume item consumption Synchronous Execution Script The script is executed synchronously before the item consumption process. Request Type Description namespace Namespace Namespace inventory Inventory Inventory itemSets ItemSet[] List of Item Sets consumeItemName string Name of Item Model consumed userId string User ID consumeCount long Quantity consumed Result Type Required Default Value Limits Description permit bool  Whether to allow item consumption overrideConsumeCount int 0 ~ 2147483645 Actual consumption to be applied Implementation Example Asynchronous Execution Script The script is executed asynchronously after the item consumption process. Request Type Description namespace Namespace Namespace oldInventory Inventory Inventory before consumption oldItemSets ItemSet[] List of Item Sets before consumption newInventory Inventory Inventory after consumption newItemSets ItemSet[] List of Item Sets after consumption consumeItemName string Name of Item Model consumed userId string User ID consumeCount long Quantity consumed Implementation Example simpleItemAcquire Simple Item acquisition Synchronous Execution Script The script is executed synchronously before the simple item acquisition process. Request Type Description namespace Namespace Namespace inventoryName string Simple Inventory Model Name The name of the simple inventory model that defines the item types for this inventory. Links the user’s simple inventory instance to its model definition. simpleItems SimpleItem[] List of Simple Items userId string User ID acquireCounts AcquireCount[] List of acquisition quantities for Simple Items Result Type Required Default Value Limits Description permit bool  Whether to allow Simple Item acquisition overrideAcquireCounts AcquireCount[] 0 ~ 100 items List of acquisition quantities for Simple Items Implementation Example Asynchronous Execution Script The script is executed asynchronously after the simple item acquisition process. Request Type Description namespace Namespace Namespace inventoryName string Simple Inventory Model Name The name of the simple inventory model that defines the item types for this inventory. Links the user’s simple inventory instance to its model definition. oldSimpleItems SimpleItem[] List of Simple Items before update newSimpleItems SimpleItem[] List of Simple Items after Update userId string User ID acquireCounts AcquireCount[] List of Simple Items Implementation Example simpleItemConsume Simple Item consumption Synchronous Execution Script The script is executed synchronously before the simple item consumption process. Request Type Description namespace Namespace Namespace inventoryName string Simple Inventory Model Name The name of the simple inventory model that defines the item types for this inventory. Links the user’s simple inventory instance to its model definition. simpleItems SimpleItem[] List of Simple Item userId string User ID consumeCounts ConsumeCount[] List of consumption quantities of Simple Items Result Type Required Default Value Limits Description permit bool  Whether to allow Simple Item consumption overrideConsumeCounts ConsumeCount[] 0 ~ 100 items List of Simple Items Implementation Example Asynchronous Execution Script The script is executed asynchronously after the simple item consumption process. Request Type Description namespace Namespace Namespace inventoryName string Simple Inventory Model Name The name of the simple inventory model that defines the item types for this inventory. Links the user’s simple inventory instance to its model definition. oldSimpleItems SimpleItem[] List of Before update Simple Items newSimpleItems SimpleItem[] List of After update Simple Items userId string User ID consumeCounts ConsumeCount[] List of consumption quantities of Simple Items Implementation Example bigItemAcquire Big Item acquisition Synchronous Execution Script The script is executed synchronously before the big item acquisition process. Request Type Description namespace Namespace Namespace inventoryName string Big Inventory Model Name The name of the big inventory model that defines the item types for this inventory. Links the user’s big inventory instance to its model definition. itemName string Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. item BigItem Big Item userId string User ID acquireCount string Acquisition quantity for a Big Item Integer value strings up to 1024 digits Result Type Required Default Value Limits Description permit bool  Whether to allow Big Item acquisition rate float 1.0 0 ~ 1000 Acquisition quantity rate Implementation Example Asynchronous Execution Script The script is executed asynchronously after the big item acquisition process. Request Type Description namespace Namespace Namespace inventoryName string Big Inventory Model Name The name of the big inventory model that defines the item types for this inventory. Links the user’s big inventory instance to its model definition. itemName string Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. oldItem BigItem Before update Big Item newItem BigItem After update Big Item userId string User ID acquireCount string Acquisition quantity for a Big Item Integer value strings up to 1024 digits Implementation Example bigItemConsume big item consumption Synchronous Execution Script The script is executed synchronously before the big item consumption process. Request Type Description namespace Namespace Namespace inventoryName string Big Inventory Model Name The name of the big inventory model that defines the item types for this inventory. Links the user’s big inventory instance to its model definition. itemName string Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. item BigItem Big Item userId string User ID consumeCount string Consumption quantity of a Big Item Integer value strings up to 1024 digits Result Type Required Default Value Limits Description permit bool  Whether to allow Big Item consumption rate float 1.0 0 ~ 1000 Consume quantity rate Implementation Example Asynchronous Execution Script The script is executed asynchronously after the big item consumption process. Request Type Description namespace Namespace Namespace inventoryName string Big Inventory Model Name The name of the big inventory model that defines the item types for this inventory. Links the user’s big inventory instance to its model definition. itemName string Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. oldItem BigItem Before update Big Item newItem BigItem After update Big Item userId string User ID consumeCount string Consumption quantity of a Big Item Integer value strings up to 1024 digits Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Inventory Script Trigger Reference","url":"/api_reference/inventory/script/"},{"content":"Trigger countUp Count up Synchronous Execution Script The script is executed synchronously before the count up process. Request Type Description namespace Namespace Namespace limitModel LimitModel Usage Limit Model counter Counter Counter userId string User ID countUpValue int Amount to count up maxValue int Maximum value allowed to count up Result Type Required Default Value Limits Description permit bool  Whether to allow count up Implementation Example Asynchronous Execution Script The script is executed asynchronously after the count up process. Request Type Description namespace Namespace Namespace limitModel LimitModel Usage Limit Model oldCounter Counter Counter before update newCounter Counter Counter after update userId string User ID countUpValue int Amount to count up maxValue int Maximum value allowed to count up Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Limit Script Trigger Reference","url":"/api_reference/limit/script/"},{"content":"Trigger receive Receive Synchronous Execution Script The script is executed synchronously before the receive process. Request Type Description namespace Namespace Namespace bonusModel BonusModel Login Bonus Model userId string User ID performing the loginReward receiveStep int Received step config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow the purchase Implementation Example Asynchronous Execution Script The script is executed asynchronously after the receive process. Request Type Description namespace Namespace Namespace bonusModel BonusModel Login Bonus Model userId string User ID performing the loginReward receiveStep int Received step config Config[] Configuration values applied to transaction variables Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-LoginReward Script Trigger Reference","url":"/api_reference/login_reward/script/"},{"content":"Trigger lottery Lottery Synchronous Execution Script The script is executed synchronously before the lottery process. Request Type Description namespace Namespace Namespace lotteryModel LotteryModel Lottery Model name drawnPrizes DrawnPrize[] List of Drawn Prizes boxItems BoxItems Box state including prizes and their remaining/initial quantities Result Type Required Default Value Limits Description permit bool  Whether to allow lottery overrideDrawnPrizes DrawnPrize[] 0 ~ 1000 items List of Drawn Prizes to override the result Implementation Example choicePrizeTable Process of dynamically selecting the Prize Table Synchronous Execution Script The script is executed synchronously before the process of dynamically selecting the prize table. Request Type Description namespace Namespace Namespace lotteryModel LotteryModel Lottery Model for dynamically selecting Prize Table userId string User ID count int Number of draws Result Type Required Default Value Limits Description prizeTableNames string[]  1 ~ 1000 items List of Prize Table names to be used for the lottery If there are 10 response values but fewer than 10 draws, they will be used in order starting from the first one. If there are 10 draws and fewer than 10 Prize Tables are responded to, the responded Prize Tables will be used in order, and the remaining draws will be conducted using the last Prize Table responded to. For example, if three Prize Tables are responded to, the first draw will use the first Prize Table, the second draw will use the second Prize Table, and the third draw and subsequent draws will use the third Prize Table. Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Lottery Script Trigger Reference","url":"/api_reference/lottery/script/"},{"content":"Trigger createGathering creating a new gathering Synchronous Execution Script The script is executed synchronously before the creating a new gathering process. Request Type Description namespace Namespace Namespace gathering Gathering Gathering Implementation Example completeMatchmaking matchmaking is complete Synchronous Execution Script The script is executed synchronously before the matchmaking is complete process. Request Type Description namespace Namespace Namespace gathering Gathering Gathering Implementation Example changeRating Rating value changes Synchronous Execution Script The script is executed synchronously before the rating value changes process. Request Type Description namespace Namespace Namespace oldRating Rating Old Rating newRating Rating New Rating Result Type Required Default Value Limits Description permit bool  Whether to allow rating value changes Implementation Example Asynchronous Execution Script The script is executed asynchronously after the rating value changes process. Request Type Description namespace Namespace Namespace oldRating Rating Old Rating newRating Rating New Rating Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Matchmaking Script Trigger Reference","url":"/api_reference/matchmaking/script/"},{"content":"Trigger missionComplete Mission accomplishment Synchronous Execution Script The script is executed synchronously before the mission accomplishment process. Request Type Description namespace Namespace Namespace missionGroupModel MissionGroupModel Mission Group oldComplete Complete Completion Status before completion newComplete Complete Completion Status after completion completeTaskNames [] List of completed task names Result Type Required Default Value Limits Description permit bool  Whether to allow mission accomplishment Implementation Example Asynchronous Execution Script The script is executed asynchronously after the mission accomplishment process. Request Type Description namespace Namespace Namespace missionGroupModel MissionGroupModel Mission Group complete Complete Completion Status completeTaskNames [] List of completed task names Implementation Example counterIncrement Counter increments Synchronous Execution Script The script is executed synchronously before the counter increments process. Request Type Description namespace Namespace Namespace counterModel CounterModel Counter Model oldCounter Counter Before Counter newCounter Counter After Counter Result Type Required Default Value Limits Description permit bool  Whether to allow counter increments Implementation Example Asynchronous Execution Script The script is executed asynchronously after the counter increments process. Request Type Description namespace Namespace Namespace counterModel CounterModel Counter Model counter Counter Counter Implementation Example receiveRewards Receive reward Synchronous Execution Script The script is executed synchronously before the receive reward process. Request Type Description namespace Namespace Namespace missionGroupModel MissionGroupModel Mission Group oldComplete Complete Completion Status before update newComplete Complete Completion Status after update receiveRewardTaskNames [] List of task names to receive rewards Result Type Required Default Value Limits Description permit bool  Whether to allow receive reward Implementation Example Asynchronous Execution Script The script is executed asynchronously after the receive reward process. Request Type Description namespace Namespace Namespace missionGroupModel MissionGroupModel Mission Group complete Complete Completion Status receiveRewardTaskNames [] List of task names to receive rewards Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Mission Script Trigger Reference","url":"/api_reference/mission/script/"},{"content":"Trigger createWallet wallet creation Synchronous Execution Script The script is executed synchronously before the wallet creation process. Request Type Description namespace Namespace Namespace wallet Wallet Wallet Result Type Required Default Value Limits Description permit bool  Whether to allow wallet creation initialAmount int  0 ~ 2147483645 Initial Wallet balance - will be credited as a free grant Implementation Example Asynchronous Execution Script The script is executed asynchronously after the wallet creation process. Request Type Description namespace Namespace Namespace wallet Wallet Wallet Implementation Example deposit Wallet balance addition Synchronous Execution Script The script is executed synchronously before the wallet balance addition process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before deposit newWallet Wallet Wallet after deposit price float Purchase Price depositCount int Quantity of premium currency to be granted Result Type Required Default Value Limits Description permit bool  Whether to allow wallet balance addition Implementation Example Asynchronous Execution Script The script is executed asynchronously after the wallet balance addition process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before deposit newWallet Wallet Wallet after deposit price float Purchase Price depositCount int Quantity of premium currency to be granted Implementation Example withdraw Wallet balance consumption Synchronous Execution Script The script is executed synchronously before the wallet balance consumption process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before withdraw newWallet Wallet Wallet after withdraw withdrawCount int Quantity of premium currency to be consumed paidOnly bool Whether to target only paid currency Result Type Required Default Value Limits Description permit bool  Whether to allow wallet balance consumption Implementation Example Asynchronous Execution Script The script is executed asynchronously after the wallet balance consumption process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before withdraw newWallet Wallet Wallet after withdraw withdrawCount int Quantity of premium currency to be consumed paidOnly bool Whether to target only paid currency Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Money Script Trigger Reference","url":"/api_reference/money/script/"},{"content":"Trigger deposit Wallet balance addition Synchronous Execution Script The script is executed synchronously before the wallet balance addition process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before deposit newWallet Wallet Wallet after deposit transactions DepositTransaction[] List of occurred transactions count int Amount of balance to be added Result Type Required Default Value Limits Description permit bool  Whether to allow wallet balance addition Implementation Example Asynchronous Execution Script The script is executed asynchronously after the wallet balance addition process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before deposit newWallet Wallet Wallet after deposit transactions DepositTransaction[] List of occurred transactions count int Amount of balance to be added Implementation Example withdraw Wallet balance consumption Synchronous Execution Script The script is executed synchronously before the wallet balance consumption process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before withdraw newWallet Wallet Wallet after withdraw transactions DepositTransaction[] List of occurred transactions count int Amount of balance to be consumed Result Type Required Default Value Limits Description permit bool  Whether to allow wallet balance consumption Implementation Example Asynchronous Execution Script The script is executed asynchronously after the wallet balance consumption process. Request Type Description namespace Namespace Namespace oldWallet Wallet Wallet before withdraw newWallet Wallet Wallet after withdraw transactions DepositTransaction[] List of occurred transactions count int Amount of balance to be consumed Implementation Example subscribe New subscription Synchronous Execution Script The script is executed synchronously before the new subscription process. Request Type Description namespace Namespace Namespace contentModel StoreSubscriptionContentModel Store Subscription Content Model transaction SubscribeTransaction Subscription Status userId string User ID ttlAt long Time to live for GS2-Schedule trigger Implementation Example renew Renewal subscription Synchronous Execution Script The script is executed synchronously before the renewal subscription process. Request Type Description namespace Namespace Namespace contentModel StoreSubscriptionContentModel Store Subscription Content Model transaction SubscribeTransaction Subscription Status userId string User ID ttlAt long Time to live for GS2-Schedule trigger Implementation Example unsubscribe Unsubscribe Synchronous Execution Script The script is executed synchronously before the unsubscribe process. Request Type Description namespace Namespace Namespace contentModel StoreSubscriptionContentModel Store Subscription Content Model transaction SubscribeTransaction Subscription Status userId string User ID Implementation Example takeOver Subscription take over Synchronous Execution Script The script is executed synchronously before the subscription take over process. Request Type Description namespace Namespace Namespace contentModel StoreSubscriptionContentModel Store Subscription Content Model transaction SubscribeTransaction Subscription Status fromUserId string User ID toUserId string User ID elapsedHours int Elapsed hours since last user change Result Type Required Default Value Limits Description permit bool  Whether to allow subscription take over Implementation Example Asynchronous Execution Script The script is executed asynchronously after the subscription take over process. Request Type Description namespace Namespace Namespace contentModel StoreSubscriptionContentModel Store Subscription Content Model transaction SubscribeTransaction Subscription Status fromUserId string User ID toUserId string User ID elapsedHours int Elapsed hours since last user change Implementation Example verifyReceipt Receipt verification Synchronous Execution Script The script is executed synchronously before the receipt verification process. Request Type Description namespace Namespace Namespace storeContentModel StoreContentModel Store Content Model receipt Receipt Receipt userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow receipt verification Implementation Example Asynchronous Execution Script The script is executed asynchronously after the receipt verification process. Request Type Description namespace Namespace Namespace storeContentModel StoreContentModel Store Content Model receipt Receipt Receipt userId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Money2 Script Trigger Reference","url":"/api_reference/money2/script/"},{"content":"Trigger startQuest Quest start Synchronous Execution Script The script is executed synchronously before the quest start process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model randomSeed long random number seed rewards Reward[] List of rewards earned from quests userId string User ID config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow the quest to begin overrideRandomSeed long 0 ~ 9223372036854775805 Random number seed overrideRewards Reward[] 0 ~ 1000 items List of rewards earned from quests Implementation Example Asynchronous Execution Script The script is executed asynchronously after the quest start process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model progress Progress Quest Progress config Config[] Configuration values applied to transaction variables Implementation Example completeQuest Quest cleared Synchronous Execution Script The script is executed synchronously before the quest cleared process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model rewards Reward[] List of rewards obtained from quests progress Progress Quest Progress config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow quests to be cleared overrideRewards Reward[] 0 ~ 1000 items List of rewards earned from quests Implementation Example Asynchronous Execution Script The script is executed asynchronously after the quest cleared process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model rewards Reward[] List of rewards obtained from quests progress Progress Quest Progress config Config[] Configuration values applied to transaction variables Implementation Example failedQuest Quest to fail Synchronous Execution Script The script is executed synchronously before the quest to fail process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model rewards Reward[] List of rewards obtained from quests progress Progress Quest Progress config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow the quest to fail overrideRewards Reward[] 0 ~ 1000 items List of rewards earned from quests Implementation Example Asynchronous Execution Script The script is executed asynchronously after the quest to fail process. Request Type Description namespace Namespace Namespace questGroupModel QuestGroupModel Quest Group Model questModel QuestModel Quest Model rewards Reward[] List of rewards obtained from quests progress Progress Quest Progress config Config[] Configuration values applied to transaction variables Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Quest Script Trigger Reference","url":"/api_reference/quest/script/"},{"content":"Trigger buy Buy Synchronous Execution Script The script is executed synchronously before the buy process. Request Type Description namespace Namespace Namespace showcase Showcase Showcase model displayItem DisplayItem DisplayItem model userId string User ID of the user executing the purchase quantity int Purchase quantity config Config[] Configuration values applied to transaction variables Result Type Required Default Value Limits Description permit bool  Whether to allow the purchase Implementation Example Asynchronous Execution Script The script is executed asynchronously after the buy process. Request Type Description namespace Namespace Namespace showcase Showcase Showcase model displayItem DisplayItem DisplayItem model userId string User ID of the user executing the purchase quantity int Purchase quantity config Config[] Configuration values applied to transaction variables Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Showcase Script Trigger Reference","url":"/api_reference/showcase/script/"},{"content":"Trigger release Release node Synchronous Execution Script The script is executed synchronously before the release node process. Request Type Description namespace Namespace Namespace oldStatus Status Status before update newStatus Status Status after update userId string User ID nodeModelNames [] List of node model names Result Type Required Default Value Limits Description permit bool  Whether to allow release node Implementation Example Asynchronous Execution Script The script is executed asynchronously after the release node process. Request Type Description namespace Namespace Namespace oldStatus Status Status before update newStatus Status Status after update userId string User ID nodeModelNames [] List of node model names Implementation Example restrain Restrain node Synchronous Execution Script The script is executed synchronously before the restrain node process. Request Type Description namespace Namespace Namespace userId string User ID oldStatus Status Status before update newStatus Status Status after update nodeModelNames [] List of node model names Result Type Required Default Value Limits Description permit bool  Whether to allow restrain node Implementation Example Asynchronous Execution Script The script is executed asynchronously after the restrain node process. Request Type Description namespace Namespace Namespace userId string User ID oldStatus Status Status before update newStatus Status Status after update nodeModelNames [] List of node model names Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-SkillTree Script Trigger Reference","url":"/api_reference/skill_tree/script/"},{"content":"Trigger overflow Stamina maximum value overflow Synchronous Execution Script The script is executed synchronously before the stamina maximum value overflow process. Request Type Description namespace Namespace Namespace staminaModel StaminaModel Stamina Model stamina Stamina Stamina overflowValue long Overflow value Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Stamina Script Trigger Reference","url":"/api_reference/stamina/script/"},{"content":"Trigger start Start state machine Synchronous Execution Script The script is executed synchronously before the start state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID parameters string Arguments to be passed to the state machine Result Type Required Default Value Limits Description permit bool  Whether to allow start Implementation Example Asynchronous Execution Script The script is executed asynchronously after the start state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID parameters string Arguments to be passed to the state machine Implementation Example pass Pass state machine Synchronous Execution Script The script is executed synchronously before the pass state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow the state machine to finish normally Implementation Example Asynchronous Execution Script The script is executed asynchronously after the pass state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID Implementation Example error Error state machine Synchronous Execution Script The script is executed synchronously before the error state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID Result Type Required Default Value Limits Description permit bool  Whether to allow an error state machine termination Implementation Example Asynchronous Execution Script The script is executed asynchronously after the error state machine process. Request Type Description namespace Namespace Namespace stateMachineMaster StateMachineMaster State machine master data status Status Status userId string User ID Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-StateMachine Script Trigger Reference","url":"/api_reference/state_machine/script/"},{"content":"Trigger acceptVersion Version approval Synchronous Execution Script The script is executed synchronously before the version approval process. Request Type Description namespace Namespace Namespace versionModel VersionModel Version Model acceptVersion AcceptVersion Agreed Version currentAcceptVersion AcceptVersion Current Agreed Version Result Type Required Default Value Limits Description permit bool  Whether to allow version approval Implementation Example Asynchronous Execution Script The script is executed asynchronously after the version approval process. Request Type Description namespace Namespace Namespace versionModel VersionModel Version Model acceptVersion AcceptVersion Agreed Version Implementation Example checkVersion Version check Synchronous Execution Script The script is executed synchronously before the version check process. Request Type Description namespace Namespace Namespace versionModel VersionModel Version Model currentVersion Version Current Version userId string User ID warning Status If the normal version check results in a warning error Status If the normal version check results in an error Result Type Required Default Value Limits Description overrideWarning Status Warning for overwritten version check results overrideError Status Error for overwritten version check results Implementation Example","lang":"en","section":"api_reference","summary":"Reference for event triggers that call extended scripts\n","title":"GS2-Version Script Trigger Reference","url":"/api_reference/version/script/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting changePasswordIfTakeOver bool false Whether to change the password when taking over the account Specifies whether to change the password when taking over the account. This setting allows you to restrict logins from the device used before the takeover after the takeover is completed. differentUserIdForLoginAndDataRetention bool false Whether to use different user IDs for login and data retention Specifies whether to use different user IDs for login and data retention. This setting may help comply with privacy requirements defined by the platform provider with less implementation effort. *This parameter can only be set when creating a namespace. createAccountScript ScriptSetting Script to run when creating an account Used to implement custom logic for creating an account. Script Trigger Reference - createAccount authenticationScript ScriptSetting Script to run when authenticated Used to implement custom logic for authentication. Script Trigger Reference - authentication createTakeOverScript ScriptSetting Script to run when creating a takeover If you want to give a reward when you register TakeOver Information for the first time, you can use this to add custom logic to increase the GS2-Mission counter. Script Trigger Reference - createTakeOver doTakeOverScript ScriptSetting Script to run when taking over Used to implement custom logic for taking over. Script Trigger Reference - doTakeOver banScript ScriptSetting Script to run when adding Account Ban Status Script Trigger Reference - ban unBanScript ScriptSetting Script to run when removing Account Ban Status Script Trigger Reference - unBan logSetting LogSetting Log Output Setting Manages Log Output Setting. This type holds the GS2-Log namespace information used to output log data. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentModelMaster Master data of the currently active TakeOver Type Model This master data defines the TakeOver Type Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Account Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentModelMaster Updated master data of the currently active TakeOver Type Model Implementation Example TakeOverTypeModel TakeOver Type Model This model defines TakeOver Information. TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.  takeOverTypeModelId string * ~ 1024 chars Takeover Type Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. OpenIdConnectSetting OpenID Connect Configuration By registering the settings of an OpenID Connect-compliant IdP, IdP integration can be configured and used as TakeOver Information.  configurationPath string  ~ 1024 chars OpenID Connect Configuration URL The discovery endpoint URL of the OpenID Connect provider. Must follow the well-known format (e.g., https://example.com/.well-known/openid-configuration). clientId string  ~ 1024 chars Client ID The client ID of the application registered with the IdP. clientSecret string {configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Client Secret * clientSecret is required when the configurationPath is not “https://appleid.apple.com/.well-known/openid-configuration”, i.e., for other IdP integrations. appleTeamId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Team ID of Apple Developer The team ID from the Apple Developer account. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” appleKeyId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Key ID registered with Apple The key ID registered in the Apple Developer account for Sign in with Apple. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” applePrivateKeyPem string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 10240 chars Private Key received from Apple The private key in PEM format downloaded from the Apple Developer portal. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” doneEndpointUrl string ~ 1024 chars Redirect URL after authentication is completed If not specified, it will transition to /authorization/done. id_token is attached to the Query String. additionalScopeValues List [] 0 ~ 10 items Additional scopes obtained with OpenID Connect Additional OAuth scopes to request from the IdP beyond the default OpenID Connect scopes. Allows retrieving extra user information during authentication. additionalReturnValues List [] 0 ~ 10 items Additional values returned from OpenID Connect Additional claim names from the ID token or UserInfo response to include in the return values. Specified claims are extracted and returned alongside the standard authentication result. ScopeValue Scope Value A key-value pair representing an additional OAuth scope value obtained during OpenID Connect authentication. Used to store extra data retrieved from the IdP beyond the standard OpenID Connect claims.  key string  ~ 64 chars Name The scope name that was requested from the IdP during authentication. value string ~ 51200 chars Value The value returned by the IdP for the corresponding scope.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Account Deploy/CDK Reference","url":"/api_reference/account/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when ad viewing rewards are granted, including auto-run, atomic commit, and asynchronous processing options. admob AdMob AdMob settings Manages settings and parameters related to ads. unityAd UnityAd Unity Ads settings Manages settings and parameters related to ads. appLovinMaxes List 0 ~ 10 items AppLovin MAX settings Manages settings and parameters related to ads. acquirePointScript ScriptSetting Script setting to be executed when points are acquired Script Trigger Reference - acquirePoint consumePointScript ScriptSetting Script setting to be executed when points are consumed Script Trigger Reference - consumePoint changePointNotification NotificationSetting  Push notification when point changes This is a push notification setting when the point changes. This setting holds the information necessary to notify the game client when the point changes. If you do not make this setting, the points you earn will not be reflected in the game immediately. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log namespace information used to output log data. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. AdMob AdMob settings Stores a list of allowed ad unit IDs and uses it to verify AdMob’s viewing completion Webhook.  allowAdUnitIds List  1 ~ 10 items List of allowed ad unit IDs Used to verify the ad unit ID included in the ad viewing completion callback from AdMob. The ad unit IDs included in this list are used to verify that the ad viewing was completed properly in the application or game. By checking whether the ad unit ID included in the notification of ad viewing completion sent from the AdMob platform is in this list, you can accept only legitimate ad viewing events and prevent invalid requests and spam. UnityAd Unity Ads settings Used to store the Unity Ads-related cryptographic keys used by the application or game. The cryptographic keys are issued by Unity Ads and are used to verify the completion of ad viewing.  keys List 0 ~ 10 items List of cryptographic keys Stores a list of cryptographic keys issued by Unity Ads. These keys are used to communicate with the Unity Ads ad platform and to verify ad events. Encryption keys can be obtained from the Unity Dashboard. Each key in the list is required to verify the completion of ad viewing. AppLovinMax AppLovin MAX settings Stores an allowed ad unit ID and uses it to verify the AppLovin MAX viewing completion Webhook.  allowAdUnitId string  ~ 16 chars Allowed Ad Unit ID Used to verify the ad_unit_id included in the AppLovin MAX ad viewing completion callback. The ad viewing event is accepted only when the ad_unit_id in the callback matches the configured ad unit ID. This prevents unauthorized callbacks, invalid requests, and fraudulent reward claims from unregistered ad units. eventKey string  ~ 128 chars AppLovin Event Key Used to verify that the completion callback from AppLovin MAX is accessed from the appropriate source.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-AdReward Deploy/CDK Reference","url":"/api_reference/ad_reward/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration that controls how distributed transactions based on buff application results are executed, including options such as AutoRun, AtomicCommit, and asynchronous processing. applyBuffScript ScriptSetting Script setting to be executed when applying buffs Script Trigger Reference - apply logSetting LogSetting Log Output Setting Configuration for outputting log data of buff operations to GS2-Log. Specifies the GS2-Log namespace where API request and response logs are collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentBuffMaster Master data of the currently active Buff Entry Models Master data that defines the Buff Entry Models currently active in the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Buff Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentBuffMaster Updated master data of the currently active Buff Entry Models Implementation Example BuffEntryModel Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period.  buffEntryModelId string * ~ 1024 chars Buff Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Buff Entry Model name Buff Entry 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Add to adjustment rate “mul” Multiply the adjustment rate by the specified value “value_add” Directly add values (only numerical values for models or actions) targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active. BuffTargetModel Buff Target Model Defines the target GS2 resource model and field for buff application. Specifies which model’s field value should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetModelName string (enum) enum { }  Model type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric field on the target model whose value will be modified by the buff. For example, a field representing experience points, attack power, or other numerical attributes. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Adjustment rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the field value after rate calculations. BuffTargetAction Buff Target Action Defines the target GS2 action and parameter for buff application. Specifies which action’s parameter should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetActionName string (enum) enum { \"Gs2Experience:AddExperienceByUserId\" , \"Gs2Experience:SubExperience\" , \"Gs2Experience:SubExperienceByUserId\" , \"Gs2Inventory:AcquireItemSetByUserId\" , \"Gs2Inventory:ConsumeItemSet\" , \"Gs2Inventory:ConsumeItemSetByUserId\" , \"Gs2Inventory:AcquireSimpleItemsByUserId\" , \"Gs2Inventory:ConsumeSimpleItems\" , \"Gs2Inventory:ConsumeSimpleItemsByUserId\" , \"Gs2Inventory:AcquireBigItemByUserId\" , \"Gs2Inventory:ConsumeBigItem\" , \"Gs2Inventory:ConsumeBigItemByUserId\" , \"Gs2Limit:CountUp\" , \"Gs2Limit:CountUpByUserId\" , \"Gs2Money:DepositByUserId\" , \"Gs2Money:Withdraw\" , \"Gs2Money:WithdrawByUserId\" , \"Gs2Money2:DepositByUserId\" , \"Gs2Money2:Withdraw\" , \"Gs2Money2:WithdrawByUserId\" , \"Gs2Stamina:ConsumeStamina\" , \"Gs2Stamina:ConsumeStaminaByUserId\" , \"Gs2Stamina:RecoverStaminaByUserId\" , }  Action type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric parameter on the target action whose value will be modified by the buff. For example, a parameter representing acquire count, consume amount, or reward quantity. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the parameter value after rate calculations. BuffTargetGrn GRN pattern that identifies the resources used as conditions for applying buffs Specifies a GRN template with placeholders to identify which resource instance the buff should be applied to. The model name identifies the GS2 service model, and the GRN pattern contains context variables (e.g., region, ownerId, namespaceName) that are resolved at runtime to match the target resource.  targetModelName string  ~ 64 chars Buff application condition model name The name of the GS2 service model used to resolve the condition GRN. This identifies which service’s resource model the GRN pattern refers to. targetGrn string  ~ 1024 chars Buff application condition GRN A GRN template with context placeholders (e.g., {region}, {ownerId}) that is resolved at runtime to identify the specific resource instance targeted by the buff.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Buff Deploy/CDK Reference","url":"/api_reference/buff/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed within the chat service. allowCreateRoom bool true Whether to allow game players to create rooms If the game operator pre-creates rooms and players subscribe to them, specify “false”. On the other hand, if the game player creates the rooms freely and invites other players to play, specify “true”. messageLifeTimeDays int 1 1 ~ 30 Message retention period (days) The number of days to keep messages in the room. postMessageScript ScriptSetting Script to run when you post a message Script Trigger Reference - postMessage createRoomScript ScriptSetting Script to run when a room is created Script Trigger Reference - createRoom deleteRoomScript ScriptSetting Script to run when a room is deleted Script Trigger Reference - deleteRoom subscribeRoomScript ScriptSetting Script to run when a room is subscribed Script Trigger Reference - subscribeRoom unsubscribeRoomScript ScriptSetting Script to run when a room is unsubscribed Script Trigger Reference - unsubscribeRoom postNotification NotificationSetting  Push notifications when new posts come to the rooms to which you are subscribed Configuration for sending push notifications via GS2-Gateway when a new message is posted to a subscribed room. Without this setting, clients must poll rooms to detect new messages. logSetting LogSetting Log Output Setting Manages log output setting. This type holds the GS2-Log Namespace information used to output log data. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway Namespace to use for push notifications Specify the GS2-Gateway Namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentModelMaster Currently active Category Model master data This master data defines the Category Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Chat Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentModelMaster Updated master data of the currently active Category Models Implementation Example CategoryModel Category Model Category Model defines the categories used to classify messages posted in chat rooms. Each category is identified by a numeric value, and you can configure whether posts using player access tokens are allowed or rejected per category. This enables use cases such as system-only announcement categories where only the server can post messages.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Chat Deploy/CDK Reference","url":"/api_reference/chat/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing datastore operations. Supports auto-run, atomic commit, and async processing options. logSetting LogSetting Log Output Setting Configuration for outputting log data of datastore operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for data object uploads, downloads, and access control changes can be collected. doneUploadScript ScriptSetting Script setting executed on upload completion (doneUpload event) Script Trigger Reference - doneUpload GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Datastore Deploy/CDK Reference","url":"/api_reference/datastore/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing dictionary entry registration. Supports auto-run, atomic commit, and async processing options. entryScript ScriptSetting Script setting to be executed when registering an entry Script Trigger Reference - entry duplicateEntryScript string ~ 1024 chars Script GRN to run when an attempt is made to re-register an entry that has already been registered Script Trigger Reference - duplicateEntry logSetting LogSetting Log Output Setting Configuration for outputting log data of dictionary operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for entry registration, like operations, and other dictionary activities can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentEntryMaster Currently active Entry Model master data This master data defines the Entry Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Dictionary Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentEntryMaster Updated master data of the currently active Entry Models Implementation Example EntryModel Entry Model An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model.  entryModelId string * ~ 1024 chars Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Entry Model name 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.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Dictionary Deploy/CDK Reference","url":"/api_reference/dictionary/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how distributed transactions are executed when processing resource distribution. Supports auto-run, atomic commit, and async processing options. assumeUserId string ~ 1024 chars GS2-Identifier User A unique resource name assigned to all information handled by GS2\" \u003e GRN autoRunStampSheetNotification NotificationSetting  Push notification when transaction auto-execution is complete(Legacy specification) Configuration for sending push notifications via GS2-Gateway when a transaction completes auto-execution on the server side. This is the legacy specification; use autoRunTransactionNotification for the new specification. autoRunTransactionNotification NotificationSetting  Push notification when transaction auto-execution is complete Configuration for sending push notifications via GS2-Gateway when a distributed transaction completes auto-execution on the server side. Notifies the client of the transaction result so it can update the local state accordingly. logSetting LogSetting Log Output Setting Configuration for outputting log data of distributor operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for resource distribution, transaction execution, and transaction processing can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentDistributorMaster Currently active Distributor Model master data This master data defines the Distributor Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Distributor Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentDistributorMaster Updated master data of the currently active Distributor Models Implementation Example DistributorModel Distributor Model A Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages.  distributorModelId string * ~ 1024 chars Distributor Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Distributor Model name Distributor 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Distributor Deploy/CDK Reference","url":"/api_reference/distributor/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing enchant parameter operations. logSetting LogSetting Log Output Setting Configuration for outputting log data of enchant operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for balance parameter and rarity parameter operations can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentParameterMaster Currently active Parameter Model master data This master data defines the Parameter Models currently active within the namespace. GS2 uses JSON format files for master data management. By uploading the file, the settings can actually be reflected on the server. To create JSON files, we provide a master data editor within the management console. Additionally, you can utilize the service by creating tools more suited to game operations and exporting JSON files in the appropriate format. Note Please refer to GS2-Enchant Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentParameterMaster Updated master data of the currently active Parameter Models Implementation Example BalanceParameterModel Balance Parameter Model Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters.  balanceParameterModelId string * ~ 1024 chars Balance Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. BalanceParameterValueModel Balance Parameter Value Model Defines a single parameter slot available within a balance parameter. Each entry specifies a named slot (e.g., ATK, DEF, SPD) that receives a portion of the total value during the drawing process.  name string  ~ 64 chars Name The identifier for this parameter slot (e.g., ATK, DEF, SPD). Must be unique within the balance parameter model. Used as the key when storing and retrieving drawn parameter values. metadata string ~ 512 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. RarityParameterModel Rarity Parameter Model Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions.  rarityParameterModelId string * ~ 1024 chars Rarity Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. RarityParameterCountModel Rarity Parameter Count Model Defines a single entry in the weighted lottery for determining how many parameter slots are granted to a resource. Each entry pairs a parameter count with a draw weight, allowing fine-grained control over the probability distribution of parameter quantities.  count int  0 ~ 10 Count The number of parameter slots to grant when this entry is drawn. For example, a count of 3 means the resource will receive 3 parameter values selected from the value model pool. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when determining the parameter count. Higher values increase the probability of this count being selected. The actual probability is this weight divided by the sum of all weights in the count model list. RarityParameterValueModel Rarity Parameter Value Model Defines a single entry in the weighted lottery pool for rarity parameter values. Each entry specifies a parameter name, game-defined resource details, and a draw weight that determines its selection probability relative to other entries in the pool.  name string  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. metadata string ~ 512 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. resourceName string  ~ 64 chars Parameter Resource Name for Game (Not used for GS2) A game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. resourceValue long  0 ~ 9223372036854775805 Parameter Resource Value for Game (Not used for GS2) A game-defined numeric value for this parameter (e.g., 50 for +50 attack power). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when selecting parameter values. Higher values increase the probability of this entry being selected. The actual probability is this weight divided by the sum of all weights in the pool.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Enchant Deploy/CDK Reference","url":"/api_reference/enchant/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing enhancement operations. Supports auto-run, atomic commit, and async processing options. enhanceScript ScriptSetting Script setting to be executed at the time of enhancement Script Trigger Reference - enhance logSetting LogSetting Log Output Setting Configuration for outputting log data of enhancement operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for enhancement and limit break operations can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentRateMaster Currently active Rate Model master data This master data defines the Rate Models currently active within the namespace. GS2 uses JSON format files for master data management. By uploading the file, the settings can actually be reflected on the server. To create JSON files, we provide a master data editor within the management console. Additionally, you can utilize the service by creating tools more suited to game operations and exporting JSON files in the appropriate format. Note Please refer to GS2-Enhance Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example RateModel Enhancement Rate Model The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity.  rateModelId string * ~ 1024 chars Enhancement Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model. acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy. acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ] Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix. bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. BonusRate Experience Gain Bonus Defines a single entry in the weighted lottery for determining the experience bonus multiplier during enhancement. By configuring multiple entries with different rates and weights, you can implement “great success” or “super success” mechanics with controlled probabilities.  rate float 1.0 0 ~ 10000 Experience bonus multiplier (1.0 = no bonus) The multiplier applied to the base experience value when this entry is drawn. A value of 1.0 means normal enhancement with no bonus, 1.5 means 150% experience (great success), 2.0 means 200% experience (super success), and so on. weight int 1 0 ~ 2147483645 Lottery weight The relative weight used in the weighted lottery when selecting the bonus rate. Higher values increase the probability of this bonus rate being selected. The actual probability is this weight divided by the sum of all weights in the bonus rate list. UnleashRateModel Unleash Rate Model Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.  unleashRateModelId string * ~ 1024 chars Unleash Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model. gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on. UnleashRateEntryModel Unleash Rate Entry Model Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade.  gradeValue long  1 ~ 1000 Target grade The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed. needCount int  1 ~ 1000 How many items of the same type to consume The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Enhance Deploy/CDK Reference","url":"/api_reference/enhance/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description enableAwaitExchange bool false Whether to enable exchanges that require a waiting time before receiving results When enabled, exchange rate models with await timing type can be used. These exchanges require real-time to elapse before rewards can be claimed, enabling crafting or production mechanics where players must wait for the result. enableDirectExchange bool true Allow direct exchange API calls When enabled, clients can call the exchange API directly to perform resource exchanges. When disabled, exchanges can only be triggered via transaction actions (transactions), providing tighter server-side control over when exchanges occur. transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how distributed transactions are executed when processing exchange operations. Supports auto-run, atomic commit, and async processing options. exchangeScript ScriptSetting Script to run when an attempt is made to perform an exchange Script Trigger Reference - exchange incrementalExchangeScript ScriptSetting Script to run when an attempt is made to perform an incremental exchange Script Trigger Reference - incrementalExchange acquireAwaitScript ScriptSetting Script setting executed when the waiting period completes and the reward is about to be acquired in an await-type exchange Script Trigger Reference - acquireAwait logSetting LogSetting Log Output Setting Configuration for outputting log data of exchange operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for exchange, incremental exchange, and await operations can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentRateMaster Currently active Rate Model master data This master data defines the Rate Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Exchange Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentRateMaster Updated master data of the currently active Rate Models Implementation Example RateModel Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange.  rateModelId string * ~ 1024 chars Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Exchange Rate Model name Exchange Rate 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action IncrementalRateModel Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis.  incrementalRateModelId string * ~ 1024 chars Incremental Cost Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script Script Trigger Reference - calculateCost * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Exchange Deploy/CDK Reference","url":"/api_reference/exchange/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing experience operations. Supports auto-run, atomic commit, and async processing options. rankCapScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to dynamically determine rank caps changeExperienceScript ScriptSetting Script setting to be executed when experience value changes Script Trigger Reference - changeExperience changeRankScript ScriptSetting Script setting to be executed when rank changes Script Trigger Reference - changeRank changeRankCapScript ScriptSetting Script setting to be executed when the rank cap changes Script Trigger Reference - changeRankCap overflowExperienceScript string ~ 1024 chars Script GRN to run when experience overflows Script Trigger Reference - overflowExperience logSetting LogSetting Log Output Setting Configuration for outputting log data of experience operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for experience value changes, rank-ups, and rank cap modifications can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentExperienceMaster Currently active Experience Model master data This master data defines the Experience Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Experience Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentExperienceMaster Updated master data of the currently active Experience Models Implementation Example ExperienceModel Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank.  experienceModelId string * ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Experience Model name Experience 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThreshold Threshold  Rank Up Threshold References the threshold table that defines the cumulative experience values required for each rank. The number of entries in the threshold determines the maximum possible rank, and each entry’s value specifies the experience needed to reach the next rank. acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. Threshold Rank Up Threshold The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained.  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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). AcquireActionRate Reward Addition Table Defines a rank-based multiplier table that adjusts reward quantities based on the status’s current rank. Each entry in the table corresponds to a rank and specifies a multiplier applied to the acquisition amount. Supports both standard double-precision values and big number string representations for large-scale calculations.  name string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. mode string (enum) enum {   “double”,   “big” } “double” Reward addition table type Selects the numeric precision for the multiplier values. Use “double” for standard floating-point numbers (up to 2^48), or “big” for string-represented numbers supporting up to 1024 digits when large-scale calculations are needed. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 10000 items Amount added per rank (multiplier) An array of multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 10000 items Amount added per rank (multiplier) An array of string-represented multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “big” for calculations requiring large-number precision. * Required if mode is “big”","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Experience Deploy/CDK Reference","url":"/api_reference/experience/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing formation operations. updateMoldScript ScriptSetting Script to run when updating Mold capacity Script Trigger Reference - updateMold updateFormScript ScriptSetting Script to run when updating a form Script Trigger Reference - updateForm updatePropertyFormScript ScriptSetting Script to run when updating a property form Script Trigger Reference - updatePropertyForm logSetting LogSetting Log Output Setting Configuration for outputting log data of formation operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for form updates, mold capacity changes, and property form modifications can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentFormMaster Currently active Form Model master data This master data defines the Form Model currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Formation Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentFormMaster Updated master data of the currently active Form Models Implementation Example FormModel Form Model Form Model is an entity representing the configuration status. You can define slots as areas that can be formed. For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots.  formModelId string * ~ 1024 chars Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Model name Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. SlotModel Slot Model Defines a single slot within a form model. A slot represents an assignable position where a game resource (such as an item, character, or equipment) can be placed. The property regex validates what values can be assigned to the slot.  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyRegex string “.*” ~ 512 chars Regular expressions for values that can be set as properties A regex pattern that validates the property ID values assignable to this slot. For example, restricting to specific GS2-Inventory item GRNs or GS2-Dictionary entry GRNs. Defaults to “.*” which allows any value. metadata string ~ 512 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. MoldModel Form Storage Area Model If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually.  moldModelId string * ~ 1024 chars Form Storage Area A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Storage Area Model name Form Storage Area 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. initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. formModel FormModel  Form Model PropertyFormModel Property Form Model An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.  propertyFormModelId string * ~ 1024 chars Property Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Property Form Model name Property Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Formation Deploy/CDK Reference","url":"/api_reference/formation/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing friend operations. followScript ScriptSetting Script to run when followed Script Trigger Reference - follow unfollowScript ScriptSetting Script to run when unfollowed Script Trigger Reference - unfollow sendRequestScript ScriptSetting Script to run when a friend request is issued Script Trigger Reference - sendRequest cancelRequestScript ScriptSetting Script to execute when a friend request is canceled Script Trigger Reference - cancelRequest acceptRequestScript ScriptSetting Script to run when a friend request is accepted Script Trigger Reference - acceptRequest rejectRequestScript ScriptSetting Script to execute when a friend request is rejected Script Trigger Reference - rejectRequest deleteFriendScript ScriptSetting Script to run when a friend is deleted Script Trigger Reference - deleteFriend updateProfileScript ScriptSetting Script to run when a profile is updated Script Trigger Reference - updateProfile followNotification NotificationSetting Push notification when followed Configuration for sending a push notification to a player when another player starts following them. Allows the followed player to be notified in real time via GS2-Gateway. receiveRequestNotification NotificationSetting  Push notification when a friend request is received Configuration for sending a push notification to a player when they receive a friend request from another player. Enables the recipient to respond promptly via GS2-Gateway. cancelRequestNotification NotificationSetting  Push notification when a received friend request is canceled Configuration for sending a push notification to a player when a friend request they previously received is canceled by the sender. Notifies the recipient that the pending request no longer exists. acceptRequestNotification NotificationSetting  Push notification when a friend request is approved Configuration for sending a push notification to a player when their sent friend request is accepted by the recipient. Both players are then added to each other’s friend lists. rejectRequestNotification NotificationSetting  Push notification when a friend request is rejected Configuration for sending a push notification to a player when their sent friend request is rejected by the recipient. The friend request is removed from both the send box and inbox. deleteFriendNotification NotificationSetting  Push notification when a friend is deleted Configuration for sending a push notification to a player when they are removed from another player’s friend list. The friendship is terminated for both sides. logSetting LogSetting Log Output Setting Configuration for outputting log data of friend operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for follow/unfollow, friend requests, and profile updates can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Friend Deploy/CDK Reference","url":"/api_reference/friend/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing gateway operations. firebaseSecret string ~ 1024 chars Secret token used to send Firebase notifications The server key or secret token for Firebase Cloud Messaging (FCM). Required to enable mobile push notification forwarding when the target player is offline and cannot receive in-game WebSocket notifications. logSetting LogSetting Log Output Setting Configuration for outputting log data of gateway operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for WebSocket session management, notification delivery, and Firebase token operations can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Gateway Deploy/CDK Reference","url":"/api_reference/gateway/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing grade operations. Supports auto-run, atomic commit, and async processing options. changeGradeScript ScriptSetting Script setting to be executed when grade changes Script Trigger Reference - changeGrade logSetting LogSetting Log Output Setting Configuration for outputting log data of grade operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for grade changes and rank cap updates can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentGradeMaster Currently active Grade Model master data This master data defines the Grade Model currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Grade Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentGradeMaster Updated master data of the currently active Grade Models Implementation Example GradeModel Grade Model A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade.  gradeModelId string * ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Grade Model name Grade 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. gradeEntries List  1 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). DefaultGradeModel Default Grade Model You can set the default grade value according to the match of the property ID regular expression when creating a new grade.  propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern matched against the property ID of a newly created grade status. When the property ID matches this pattern, the specified default grade value is assigned as the initial grade instead of 0. Patterns are evaluated in order, and the first match is used. defaultGradeValue long  0 ~ 9223372036854775805 Default Grade Value The initial grade value assigned to a newly created status when its property ID matches the propertyIdRegex pattern. This value determines the starting rank cap for the linked GS2-Experience model, as the grade entry at this index defines the corresponding rank cap. GradeEntryModel Grade Entry Model Defines the mapping between a grade value and a rank cap for the linked GS2-Experience model. Each entry also specifies regex patterns for matching property IDs, enabling the system to determine which resources can be used for grade-up operations and how their property IDs are transformed.  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. rankCapValue long  0 ~ 9223372036854775805 Rank Cap Value The rank cap value to set in the linked GS2-Experience model when this grade is applied. When a player’s grade changes to the value corresponding to this entry, the rank cap of the associated experience status is automatically updated to this value, controlling the maximum achievable rank. propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern applied to the grade status’s property ID to extract variables for grade-up matching. Capture groups (parenthesized parts) in this pattern become available as $1, $2, etc. in gradeUpPropertyIdRegex. For example, a pattern like “character-(.+)” extracts the character identifier for use in matching grade-up material property IDs. gradeUpPropertyIdRegex string  ~ 1024 chars Grade-Up Property ID Regex A regular expression pattern that identifies which resource property IDs can be consumed for grade advancement. This pattern can reference capture groups from propertyIdRegex using $1, $2, etc. For example, if propertyIdRegex extracts “sword-001” as $1, this pattern might be “grade-up-material-$1” to match materials specific to that sword. AcquireActionRate Reward Addition Table Defines a named multiplier table that scales reward amounts based on the current grade value. Each grade value maps to a multiplier applied to acquire actions in transactions, allowing higher-graded characters or equipment to receive proportionally more rewards. Supports both standard double-precision mode and big number mode for extremely large values.  name string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. mode string (enum) enum {   “double”,   “big” } “double” Reward Addition Table Type Selects the numeric precision mode for multiplier values. “double” mode uses standard floating-point numbers suitable for most cases. “big” mode uses string-represented numbers supporting up to 1024 digits, for games requiring extremely large value calculations. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 1000 items Multiplier List per Grade (double mode) An array of reward multipliers indexed by grade value, using double-precision floating-point numbers. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 1000 items Multiplier List per Grade (big mode) An array of reward multipliers indexed by grade value, using string-represented numbers for extended precision. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “big” for games requiring very large number calculations. * Required if mode is “big”","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Grade Deploy/CDK Reference","url":"/api_reference/grade/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description blockingPolicy BlockingPolicyModel  Blocking Policy The security policy configuration for this namespace that controls access to GS2 services. Defines which services are accessible, geo-restriction rules, anonymous IP detection, hosting provider IP detection, reputation-based IP filtering, and custom IP address allow/deny lists. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example BlockingPolicyModel Blocking Policy Defines the comprehensive access control rules for a GS2-Guard namespace. Combines multiple security layers including service-level access control, geo-restriction by country, anonymous IP detection (Tor/proxy), hosting provider IP detection (VPN/rental servers), IP reputation filtering, and custom IP address allow/deny lists.  passServices List  1 ~ 100 items List of Accessible GS2 Services The list of GS2 services that clients are allowed to access through this guard namespace. Only services included in this list will be protected by the blocking policy. At least one service must be specified. defaultRestriction string (enum) enum {   “Allow”,   “Deny” } “Allow” Default Restriction The default action applied to requests that do not match any of the configured detection rules. “Allow” permits all unmatched traffic (blocklist approach), while “Deny” blocks all unmatched traffic (allowlist approach). Definition Description “Allow” Allow access that does not match the conditions “Deny” Deny access that does not match the conditions locationDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Location Detection Enables or disables geo-restriction based on the client’s country of origin. When enabled, access is filtered by country. The specific countries and the allow/deny behavior are configured via the locations and locationRestriction fields. Definition Description “Enable” Enable “Disable” Disable locations List {locationDetection} == “Enable” [] 1 ~ 100 items List of Countries to Detect Access The list of countries used for geo-restriction filtering. Each country is specified using ISO 3166-1 alpha-2 country codes. Whether these countries are allowed or denied is determined by the locationRestriction setting. Only effective when locationDetection is enabled. * Enabled only if locationDetection is “Enable” locationRestriction string (enum) enum {   “Allow”,   “Deny” } {locationDetection} == “Enable”  Location Restriction Action The action to take when a request originates from a country in the locations list. “Allow” permits access only from listed countries (allowlist), while “Deny” blocks access from listed countries (blocklist). Works in conjunction with locationDetection and the locations list. Definition Description “Allow” Allow access “Deny” Deny access * Required if locationDetection is “Enable” anonymousIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Anonymous IP Service Detection Enables or disables detection of access from anonymous IP services such as Tor exit nodes and public proxies. When enabled, requests from these sources are identified and evaluated. Definition Description “Enable” Enable “Disable” Disable anonymousIpRestriction string (enum) enum {   “Deny” } {anonymousIpDetection} == “Enable” “Deny” Anonymous IP Restriction Action The action to take when access from an anonymous IP service (Tor/public proxy) is detected. Currently only supports “Deny” to block such access. Only effective when anonymousIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if anonymousIpDetection is “Enable” hostingProviderIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Hosting Provider IP Detection Enables or disables detection of access from hosting provider IP addresses such as public VPN services and rental servers. When enabled, traffic originating from cloud infrastructure or hosting services rather than end-user devices is identified and evaluated. Definition Description “Enable” Enable “Disable” Disable hostingProviderIpRestriction string (enum) enum {   “Deny” } {hostingProviderIpDetection} == “Enable” “Deny” Hosting Provider IP Restriction Action The action to take when access from a hosting provider IP (public VPN/rental server) is detected. Currently only supports “Deny” to block such access. Only effective when hostingProviderIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if hostingProviderIpDetection is “Enable” reputationIpDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” Reputation IP Detection Enables or disables detection of access from IP addresses with a known bad reputation. When enabled, IPs associated with bots, DDoS attacks, and other malicious activities are identified and evaluated. Definition Description “Enable” Enable “Disable” Disable reputationIpRestriction string (enum) enum {   “Deny” } {reputationIpDetection} == “Enable” “Deny” Reputation IP Restriction Action The action to take when access from an IP with a bad reputation is detected. Currently only supports “Deny” to block such access. Only effective when reputationIpDetection is enabled. Definition Description “Deny” Deny * Enabled only if reputationIpDetection is “Enable” ipAddressesDetection string (enum) enum {   “Enable”,   “Disable” } “Disable” IP Address Detection Enables or disables custom IP address-based access filtering. When enabled, requests are evaluated against the custom IP address list specified in the ipAddresses field. The allow/deny behavior is controlled by ipAddressRestriction. Definition Description “Enable” Enable “Disable” Disable ipAddresses List {ipAddressesDetection} == “Enable” 0 ~ 100 items List of IP Address Ranges A list of IP address ranges in CIDR notation used for custom IP-based access filtering. Each incoming request’s source IP is evaluated against these ranges. Whether matching IPs are allowed or denied is controlled by ipAddressRestriction. Only effective when ipAddressesDetection is enabled. * Enabled only if ipAddressesDetection is “Enable” ipAddressRestriction string (enum) enum {   “Allow”,   “Deny” } {ipAddressesDetection} == “Enable”  IP Address Restriction Action The action to take when a request’s source IP matches the custom IP address list. “Allow” permits access only from listed IPs (allowlist), while “Deny” blocks access from listed IPs (blocklist). Only effective when ipAddressesDetection is enabled. Definition Description “Allow” Allow access “Deny” Deny access * Required if ipAddressesDetection is “Enable”","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Guard Deploy/CDK Reference","url":"/api_reference/guard/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how distributed transactions are executed when processing guild operations. Supports auto-run, atomic commit, and async processing options. changeNotification NotificationSetting Guild Change Notification Push notification sent via GS2-Gateway when guild information (display name, attributes, join policy, etc.) is updated. Allows guild members to receive real-time updates about changes to their guild. joinNotification NotificationSetting Member Join Notification Push notification sent via GS2-Gateway when a new member joins the guild, either through direct join (open policy) or after approval of a join request. Enables existing members to be notified of new additions. leaveNotification NotificationSetting Member Leave Notification Push notification sent via GS2-Gateway when a member leaves or is removed from the guild. Covers both voluntary departures and expulsions by guild masters. changeMemberNotification NotificationSetting Member Change Notification Push notification sent via GS2-Gateway when a guild member’s information (role, metadata) is updated. Whether metadata changes trigger this notification can be controlled with changeMemberNotificationIgnoreChangeMetadata. changeMemberNotificationIgnoreChangeMetadata bool? false Whether to ignore changes in metadata when issuing notifications when member metadata is updated receiveRequestNotification NotificationSetting Receive Request Notification Push notification sent via GS2-Gateway when the guild receives a new join request from a user. Allows guild masters and authorized members to be notified of pending requests that require approval. removeRequestNotification NotificationSetting Remove Request Notification Push notification sent via GS2-Gateway when a guild join request is deleted, either by cancellation from the sender, rejection by the guild, or approval (which removes the request and adds the member). createGuildScript ScriptSetting Script to execute when creating a Guild Script Trigger Reference - createGuild updateGuildScript ScriptSetting Script to execute when update a guild Script Trigger Reference - updateGuild joinGuildScript ScriptSetting Script to execute when joining a guild Script Trigger Reference - joinGuild receiveJoinRequestScript ScriptSetting Script to execute when receiving a guild join request Script Trigger Reference - receiveJoinRequest leaveGuildScript ScriptSetting Script to execute when leaving a guild Script Trigger Reference - leaveGuild changeRoleScript ScriptSetting Script to execute when changing the role assigned to a member Script Trigger Reference - changeRole deleteGuildScript ScriptSetting Script to execute when deleting a guild Script Trigger Reference - deleteGuild logSetting LogSetting Log Output Setting Configuration for outputting log data of guild operations to GS2-Log. By specifying a GS2-Log namespace, API request and response logs for guild creation, joining, leaving, and role changes can be collected. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentGuildMaster Currently active Guild Model master data This master data defines the Guild Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Guild Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentGuildMaster Updated master data of the currently active Guild Models Implementation Example 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.  guildModelId string * ~ 1024 chars Guild Model A unique resource name assigned to all information handled by GS2\" \u003e 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  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.  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.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Guild Deploy/CDK Reference","url":"/api_reference/guild/deploy/"},{"content":"Entities Resources managed by the Deploy operation Identifier Credential Credentials used to access the GS2 API. A credential consists of a client ID and a client secret, and access using the credential is restricted based on the privileges of the user who owns the credential. Request Resource creation and update requests  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this credential. The credential inherits the permissions of this user based on the security policies attached to them. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Identifier Created Credential ClientSecret string Client Secret Implementation Example Password Password Password for logging into the Management Console based on user permissions. A password allows different accounts to log in to a single project and still limit the information they have access to. Request Resource creation and update requests  userName string  ~ 128 chars User Name The name of the GS2-Identifier user who owns this password. The user logs into the management console with this user name and the corresponding password, and access is restricted based on the security policies attached to the user. password string  ~ 1024 chars Password The hashed password used for management console authentication. Set during password creation and verified against user input at login time. Stored internally and never returned through the API. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Password Created Password Implementation Example AttachSecurityPolicy Attached Security Policy Manages the association between a GS2-Identifier user and their security policies. Each user has one attachment record that contains the list of security policy GRNs applied to that user. When the user’s credentials are used for API access, all attached policies are evaluated to determine whether the requested operation is allowed or denied. Request Resource creation and update requests  userName string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). securityPolicyId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Security Policy to assign GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Items SecurityPolicy[] List of Security Policies assigned to a user Implementation Example User GS2-Identifier User This entity represents a game developer who has access to the project. The user has credentials for programmatic access and A password can be registered that allows the user to log into the Management Console and manage the project based on the user’s permissions. Request Resource creation and update requests  name string  ~ 128 chars GS2-Identifier User name GS2-Identifier User-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item User Created User Implementation Example SecurityPolicy Security Policy Define restrictions on the types of APIs that users can use and the resources they can access. Access restriction rules are defined using JSON format definition data called policy documents. For the specifications of policy documents, please refer to the explanation page on policy documents in the development documents. Request Resource creation and update requests  name string  ~ 128 chars Security Policy Name Security Policy-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description policy string  ~ 524288 chars Policy Document A JSON document that defines the access control rules for this security policy. The document specifies which GS2 API actions are allowed or denied, and which resources (identified by GRN patterns) the rules apply to. Multiple statements can be combined to create fine-grained access control. Maximum 512KB. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item SecurityPolicy Created security policy Implementation Example","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Identifier Deploy/CDK Reference","url":"/api_reference/identifier/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting idle rewards. receiveScript ScriptSetting Script setting executed when rewards are received Script Trigger Reference - receive overrideAcquireActionsScriptId string ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN for dynamically determining idle reward Acquire Actions logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to idle reward operations. Useful for tracking idle status creation, reward claims, and debugging timing issues. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue Namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentCategoryMaster Currently active Category Model master data This master data defines the Category Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Idle Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentCategoryMaster Updated master data of the currently active Category Models Implementation Example CategoryModel Category Model A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. AcquireActionList Acquire Action List A wrapper that groups multiple acquire actions to be granted together for a single reward interval. Each AcquireActionList corresponds to one reward cycle in the category model’s acquireActions array, enabling different reward combinations at each interval.  acquireActions List [] 0 ~ 100 items List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. AcquireAction Acquire Action Represents a single acquire action used as an idle reward. Consists of an action type (e.g., add items, increase currency) and its request parameters. When idle rewards are claimed, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Idle Deploy/CDK Reference","url":"/api_reference/idle/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description isAutomaticDeletingEnabled bool false Automatic Deletion When enabled, messages are automatically removed from the user’s message list after they are opened (read). This keeps the inbox clean by removing claimed messages without requiring an explicit delete operation from the client. When disabled, opened messages remain in the list until manually deleted. transactionSetting TransactionSetting Transaction Setting Configuration for distributed transaction processing (transactions) used when granting rewards attached to messages. When a message with readAcquireActions is opened, transactions are generated and executed to deliver the rewards. Supports auto-run, atomic commit, and asynchronous processing. receiveMessageScript ScriptSetting Script to run when a message is received Script Trigger Reference - receiveMessage readMessageScript ScriptSetting Script to run when a message is opened Script Trigger Reference - readMessage deleteMessageScript ScriptSetting Script to run when a message is deleted Script Trigger Reference - deleteMessage receiveNotification NotificationSetting Receive Notification Push Notification Setting triggered when a new message is delivered to a user’s inbox. Uses GS2-Gateway to send real-time notifications to the game client, allowing the UI to display a new message indicator or refresh the inbox without polling. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs related to message operations. Useful for tracking message delivery, opening, reward claims, and deletion for auditing and debugging purposes. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentMessageMaster Currently active Global Message master data This master data defines the Global Messages currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Inbox Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentMessageMaster Updated master data of the currently active Global Messages Implementation Example GlobalMessage Global Message Global Message is a mechanism for delivering messages to all game players. Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message. Unreceived Global Messages within the validity period are copied to the player’s message box.  globalMessageId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Global Message for all users * Set automatically by the server name string  ~ 128 chars Global Message name Global Message-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. TimeSpan Time Span Represents a duration of time as a combination of days, hours, and minutes. Used to define the expiration period for messages relative to their reception time. For example, a TimeSpan of 7 days, 0 hours, 0 minutes means the message expires exactly one week after the user receives it.  days int 0 0 ~ 365 Days The number of days in this time span. Combined with hours and minutes to calculate the total duration. Maximum 365 days. hours int 0 0 ~ 24 Hours The number of hours in this time span. Combined with days and minutes to calculate the total duration. Maximum 24 hours. minutes int 0 0 ~ 60 Minutes The number of minutes in this time span. Combined with days and hours to calculate the total duration. Maximum 60 minutes. AcquireAction Acquire Action Represents a single acquire action attached to a message as a reward. Consists of an action type (e.g., add items to inventory, increase currency) and its request parameters. When a message is opened, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Inbox Deploy/CDK Reference","url":"/api_reference/inbox/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configures distributed transaction processing for inventory operations such as acquiring and consuming items. Supports auto-run mode for seamless execution, atomic commit for consistent multi-resource operations, and async processing for large-scale reward distribution. acquireScript ScriptSetting Script setting to be executed when an Items is acquired Script Trigger Reference - acquire overflowScript ScriptSetting Script to execute when unable to obtain due to reaching the acquisition limit Script Trigger Reference - overflowDone consumeScript ScriptSetting Script to run when consuming Items Script Trigger Reference - consume simpleItemAcquireScript ScriptSetting Script setting to be executed when acquiring Simple Items Script Trigger Reference - simpleItemAcquire simpleItemConsumeScript ScriptSetting Script to run when consuming Simple Items Script Trigger Reference - simpleItemConsume bigItemAcquireScript ScriptSetting Script setting to be executed when acquiring Big Items Script Trigger Reference - bigItemAcquire bigItemConsumeScript ScriptSetting Script to run when consuming Big Items Script Trigger Reference - bigItemConsume logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of inventory operations. Useful for tracking item acquisition, consumption, and capacity changes for debugging and analytics. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentItemModelMaster Currently active Item Model master data This master data defines the Item Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Inventory Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentItemModelMaster Updated master data of the currently active Item Models Implementation Example InventoryModel Inventory Model Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity.  inventoryModelId string * ~ 1024 chars Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Inventory Model name Inventory 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool? false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. itemModels List [] 1 ~ 1000 items List of Item Models The item types that can be stored in this inventory. Each item model defines the stacking and acquisition behavior for one type of item. Up to 1000 item models per inventory model. ItemModel Item Model Items can be held in groups within a single inventory slot, such as Potion ×99. This grouping of multiple items into one slot is called “stacking,” and a maximum stack size can be set for each item. The behavior when the stack limit is reached can also be set for each item. Specifically, you can choose one of the following: Add a new inventory slot to allow further acquisition Prevent further acquisition once the limit is reached  itemModelId string * ~ 1024 chars Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. SimpleInventoryModel Simple Inventory Model In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation.  inventoryModelId string * ~ 1024 chars Simple Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Inventory Model name Simple Inventory 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. simpleItemModels List [] 1 ~ 1000 items List of Simple Item Models The item types that can be stored in this simple inventory. Unlike standard inventory, simple items have no stacking limits or capacity constraints. Up to 1000 item models per simple inventory model. SimpleItemModel Simple Item Model ItemModel allowed setting a maximum stackable quantity, enabling implementation where items exceeding a certain number could be split into multiple stacks. SimpleItem does not have such a function and simply stores the number of items in the possession of the item.  itemModelId string * ~ 1024 chars Simple Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Item Model name Simple Item 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. BigInventoryModel Big Inventory Model In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits.  inventoryModelId string * ~ 1024 chars Big Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Inventory Model name Big Inventory 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. bigItemModels List [] 1 ~ 1000 items List of Big Item Models The item types that can be stored in this big inventory. Each big item model can hold quantities represented as integer strings up to 1024 digits. Up to 1000 item models per big inventory model. BigItemModel Big Item Model The Big Item Model defines items stored in a Big Inventory Model. Big Items can hold quantities that exceed the range of int64.  itemModelId string * ~ 1024 chars Big Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Item Model name Big Item 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.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Inventory Deploy/CDK Reference","url":"/api_reference/inventory/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing job queue operations. enableAutoRun bool false Whether to automatically execute jobs on the server side When enabled, registered jobs are automatically executed on the server side without requiring the client to poll and run them. When disabled, the client must explicitly call the run API to process jobs, and a pushNotification can be used to notify the client of new jobs. pushNotification NotificationSetting !{enableAutoRun} Push Notification Push Notification Setting via GS2-Gateway when a new job is registered in the job queue. Only available when enableAutoRun is disabled. Used to prompt the client to call the run API to process the newly registered job. * Enabled only if enableAutoRun is “false” runNotification NotificationSetting  Run Notification Push Notification Setting via GS2-Gateway when a job in the job queue is executed. The notification includes the job result, allowing the client to display rewards or handle errors without additional API calls. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of job queue operations. Useful for tracking job registration, execution, retry, and failure for debugging and analytics. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-JobQueue Deploy/CDK Reference","url":"/api_reference/job_queue/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of encryption key operations. Useful for auditing key usage such as encryption and decryption requests. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Key Encryption Key The GRN of the Encryption Key to be created here must be specified when encryption processing is required by GS2. The contents of the specific Encryption Key will not be disclosed outside of GS2, and encryption and decryption can be performed securely. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Encryption Key name Encryption Key-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Key Encryption Key created Implementation Example","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Key Deploy/CDK Reference","url":"/api_reference/key/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing limit operations such as counting up and resetting counters. countUpScript ScriptSetting Script to execute when counting up Script Trigger Reference - countUp logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of limit operations. Useful for tracking counter increments, resets, and limit checks for debugging and analytics. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentLimitMaster Currently active Usage Limit Model master data This master data defines the Usage Limit Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Limit Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentLimitMaster Updated master data of the currently active Usage Limit Models Implementation Example LimitModel Usage Limit Model Usage Limit Model allows you to set the timing for resetting the usage count. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. Additionally, the maximum value for usage Limits is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha: Items purchasable when the purchase counter is under 3 When the above items are unavailable, another item purchasable if the purchase counter is under 5 The design assumes the ability to switch the “maximum count” based on the situation.  limitModelId string * ~ 1024 chars Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Usage Limit Model name Usage Limit 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days”","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Limit Deploy/CDK Reference","url":"/api_reference/limit/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log Namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified Namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Lock Deploy/CDK Reference","url":"/api_reference/lock/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the Namespace differs, the data is treated as a completely independent data space. Therefore, you must create a Namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description type string (enum) enum {   “gs2”,   “bigquery”,   “firehose” } “gs2” Log Export Method Determines the destination for exported log data. “gs2” stores logs within GS2’s managed storage with built-in search and analysis capabilities. “bigquery” exports logs to Google BigQuery for advanced analytics. “firehose” streams logs to Amazon Kinesis Data Firehose for delivery to S3, Redshift, or other AWS destinations. Definition Description “gs2” Management by GS2 “bigquery” Export to BigQuery “firehose” Export to Kinesis Firehose gcpCredentialJson string {type} == “bigquery”  ~ 5120 chars GCP Credentials GCP credential JSON for authenticating when exporting logs to BigQuery. The service account must have BigQuery Data Editor permissions on the target dataset. * Required if type is “bigquery” bigQueryDatasetName string {type} == “bigquery”  ~ 1024 chars BigQuery Dataset Name The name of the BigQuery dataset where log data will be exported. The dataset must already exist in the GCP project associated with the provided credentials. * Required if type is “bigquery” logExpireDays int {type} in [“gs2”, “bigquery”]  0 ~ 3650 Log Retention Period (days) The number of days to retain log data. Logs older than this period are automatically deleted. Applicable when the export method is “gs2” or “bigquery”. Maximum 3650 days (approximately 10 years). * Required if type is “gs2”,“bigquery” awsRegion string {type} == “firehose”  ~ 256 chars AWS Region The AWS region where the Kinesis Data Firehose delivery stream is located (e.g., us-east-1, ap-northeast-1). * Required if type is “firehose” awsAccessKeyId string {type} == “firehose”  ~ 256 chars AWS Access Key ID The AWS access key ID for authenticating with Kinesis Data Firehose. The IAM user must have permissions to put records to the specified Firehose delivery stream. * Required if type is “firehose” awsSecretAccessKey string {type} == “firehose”  ~ 256 chars AWS Secret Access Key The AWS secret access key paired with the access key ID for Kinesis Data Firehose authentication. * Required if type is “firehose” firehoseStreamName string {type} == “firehose”  ~ 256 chars Kinesis Firehose Stream Name The name of the Kinesis Data Firehose delivery stream to which log data is sent. * Required if type is “firehose” firehoseCompressData string (enum) enum {   “none”,   “gzip” } {type} == “firehose” “none” Compress Data for Kinesis Firehose Whether to compress log data before sending to Kinesis Data Firehose. Gzip compression reduces data transfer volume and storage costs. Definition Description “none” Do not compress “gzip” Gzip * Required if type is “firehose” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example Dashboard Dashboard A customizable dashboard for visualizing log data and metrics. Each dashboard stores its layout and widget configuration as a JSON payload, allowing users to create tailored views of their log analytics. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). displayName string  ~ 256 chars Display Name A human-readable name for this dashboard, shown in the dashboard list and header. description string ~ 1024 chars Description GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Dashboard Created Dashboard Implementation Example FacetModel Facet Model Defines a facet field available for filtering and aggregating log data. Facets allow users to narrow down log search results by specific dimensions such as service name, method, status, or custom fields. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). field string  ~ 128 chars Facet Field Name The name of the log field that this facet operates on (e.g., “service”, “method”, “status”). type string (enum) enum {   “string”,   “double”,   “measure” }  Facet Data Type The data type of the facet field. “string” for categorical values with value counts, “double” for numeric values with range filtering, “measure” for measurement values with statistical analysis. Definition Description “string” String “double” Double “measure” Measure displayName string  ~ 128 chars Display Name A human-readable name for this facet, shown in the log search UI. order int 0 0 ~ 100000 Display Order The sort order for displaying this facet in the UI. Lower values appear first. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item FacetModel Created Facet Model Implementation Example","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Log Deploy/CDK Reference","url":"/api_reference/log/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for how reward transactions are executed within this namespace. receiveScript ScriptSetting Script to run when receiving rewards Script Trigger Reference - receive logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, login bonus operations (receive, missed recovery, etc.) are logged for monitoring and analysis. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentBonusMaster Currently active Login Bonus Model master data This master data defines the Login Bonus Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-LoginReward Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentBonusMaster Updated master data of the currently active Login Bonus Models Implementation Example BonusModel Login Bonus Model Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days.  bonusModelId string * ~ 1024 chars Login Bonus Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Login Bonus Model name Login Bonus 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. resetHour int {periodEventId} == \"\"  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Reward Reward Represents a single day’s reward configuration for a login bonus. Each Reward contains a list of acquire actions that define what the user receives (e.g., items, currency, experience). The rewards array in BonusModel holds one Reward per day, distributed in order. Reward values can be modified at runtime through the buff system (BonusModelBuff) to apply rate multipliers to acquire actions.  acquireActions List  1 ~ 10 items List of Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies an acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. ConsumeAction Consume Action Defines an action for consuming resources from a user via the transaction mechanism. Used in missed-bonus recovery to specify the cost users must pay (e.g., deducting currency, consuming items). The action field specifies the type of consume action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action Defines an action for granting resources to a user via the transaction mechanism. Used within rewards to specify what the user receives (e.g., adding items to inventory, granting currency, awarding experience points). The action field specifies the type of acquire action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-LoginReward Deploy/CDK Reference","url":"/api_reference/login_reward/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing lottery operations. Lottery draws issue transactions that grant prizes to users via acquire actions. lotteryTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be called when the lottery is executed logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs of lottery operations. Useful for tracking draw results, prize distributions, and box gacha states for debugging and analytics. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentLotteryMaster Currently active Lottery Model master data This master data defines the Lottery Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Lottery Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentLotteryMaster Updated current active Lottery Model master data Implementation Example PrizeTable Prize Table A prize can either specify an acquire action directly or reference another Prize Table. By nesting Prize Tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game.  prizeTableId string * ~ 1024 chars Prize Table A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. Prize Prize A single prize entry within a Prize Table. A prize can either directly specify acquire actions (granting items, currency, etc.) or reference another Prize Table to perform a nested draw. Each prize has a draw weight that determines its relative probability of being drawn.  prizeId string  UUID ~ 36 chars Prize ID A unique identifier for this prize within the Prize Table. Used to track draw limits and as a reference when specifying failover prizes. type string (enum) enum {   “action”,   “prize_table” }  Prize Type Determines whether this prize directly grants rewards or delegates to another Prize Table. “action” specifies acquire actions to execute when drawn. “prize_table” references another Prize Table for a nested drawing (e.g., first draw determines rarity, second draw determines specific item). Definition Description “action” Acquire Actions for the prize “prize_table” Delegates the draw to another Prize Table (performs a nested draw). acquireActions List {type} == “action” [] 1 ~ 100 items List of Acquire Actions The list of acquire actions to execute when this prize is drawn. Multiple actions can be specified to grant several rewards at once (e.g., an item and currency together). * Enabled only if type is “action” drawnLimit int {type} == “action” 1 ~ 1000000 Maximum Number of Draws The maximum number of times this prize can be drawn across all users. When the limit is reached, the failover prize (limitFailOverPrizeId) is drawn instead. Used to implement limited-quantity prizes such as jackpot items. * Enabled only if type is “action” limitFailOverPrizeId string {type} == “action” and {drawnLimit} \u003e 0  ~ 32 chars Limit Failover Prize ID The ID of the prize to draw instead when this prize’s draw limit (drawnLimit) has been reached. Must reference another prize within the same Prize Table. * Required if type is “action” and drawnLimit is greater than 0 prizeTableName string {type} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to delegate the draw to. Used when the prize type is “prize_table” for nested drawing. * Required if type is “prize_table” weight int  1 ~ 2147483646 Draw Weight The relative weight of this prize in the Prize Table. The actual draw probability is calculated as this prize’s weight divided by the total weight of all prizes in the table. For example, if three prizes have weights of 70, 20, and 10, their draw probabilities are 70%, 20%, and 10% respectively. LotteryModel Lottery Model Lottery Model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha.  lotteryModelId string * ~ 1024 chars Lottery Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios like applying a different Prize Table for one draw in a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table Script Trigger Reference - choicePrizeTable * Required if method is “script” AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Lottery Deploy/CDK Reference","url":"/api_reference/lottery/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing matchmaking operations. enableRating bool false Enable Rating Whether to enable the Glicko-2 based rating calculation function. When enabled, players can submit match results via the Vote system and have their ratings automatically updated. Requires RatingModel master data to be configured. Defaults to false. enableDisconnectDetection string (enum) enum {   “disable”,   “enable” } “disable” Disconnect Detection Controls whether players in matchmaking must periodically report they are still waiting. When enabled, if a player does not send a keep-alive within the configured timeout period, they are automatically removed from the Gathering. This prevents “ghost” players from blocking matchmaking completion. Defaults to “disable”. Definition Description “disable” Disable “enable” Enable disconnectDetectionTimeoutSeconds int {enableDisconnectDetection} == “enable”  15 ~ 600 Disconnect Detection Timeout (seconds) The number of seconds to wait without a keep-alive report before a player is considered disconnected and removed from the Gathering. Only applies when disconnect detection is enabled. Must be between 15 and 600 seconds. * Required if enableDisconnectDetection is “enable” createGatheringTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Create Gathering Trigger Type The type of action to execute when a new Gathering is created. Can trigger GS2-Realtime room creation for real-time communication, or execute a GS2-Script for custom logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution createGatheringTriggerRealtimeNamespaceId string {createGatheringTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace to create rooms when creating a gathering * Required if createGatheringTriggerType is “gs2_realtime” createGatheringTriggerScriptId string {createGatheringTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when creating a gathering * Required if createGatheringTriggerType is “gs2_script” completeMatchmakingTriggerType string (enum) enum {   “none”,   “gs2_realtime”,   “gs2_script” } “none” Complete Matchmaking Trigger Type The type of action to execute when matchmaking completes (all role slots are filled). Can trigger GS2-Realtime room creation for the matched players, or execute a GS2-Script for custom post-match logic. Defaults to “none”. Definition Description “none” None “gs2_realtime” GS2-Realtime Room Creation “gs2_script” GS2-Script Execution completeMatchmakingTriggerRealtimeNamespaceId string {completeMatchmakingTriggerType} == “gs2_realtime”  ~ 1024 chars GS2-Realtime namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to create rooms when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_realtime” completeMatchmakingTriggerScriptId string {completeMatchmakingTriggerType} == “gs2_script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed when matchmaking is complete * Required if completeMatchmakingTriggerType is “gs2_script” enableCollaborateSeasonRating string (enum) enum {   “enable”,   “disable” } “disable” Enable Season Rating Collaboration Whether to enable integration with GS2-SeasonRating for season-based rating calculations. When enabled, a rating calculation session is automatically created in the specified GS2-SeasonRating namespace when matchmaking completes. Defaults to “disable”. Definition Description “enable” Enable “disable” Disable collaborateSeasonRatingNamespaceId string {enableCollaborateSeasonRating} == “enable”  ~ 1024 chars Season Rating Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if enableCollaborateSeasonRating is “enable” collaborateSeasonRatingTtl int {enableCollaborateSeasonRating} == “enable” 60 60 ~ 7200 Season Rating Result TTL (seconds) The maximum time in seconds to wait for match result submissions via GS2-SeasonRating after matchmaking completes. If results are not submitted within this period, the rating session expires. Must be between 60 and 7200 seconds. Defaults to 60. * Required if enableCollaborateSeasonRating is “enable” changeRatingScript ScriptSetting Script setting to be executed when the rating value changes Script Trigger Reference - changeRating joinNotification NotificationSetting Join Notification Push Notification Setting for when a new player joins a Gathering. Notifies existing participants that a new player has joined, allowing the game client to update the matchmaking UI. leaveNotification NotificationSetting Leave Notification Push Notification Setting for when a player leaves a Gathering. Notifies remaining participants that a player has left, allowing the game client to reflect the change. completeNotification NotificationSetting Complete Notification Push Notification Setting for when matchmaking completes (all role slots are filled). Notifies all participants that the Gathering is full and the match can begin. changeRatingNotification NotificationSetting Change Rating Notification Push Notification Setting for when a player’s rating value changes after vote processing. Notifies the affected player of their new rating, allowing the game client to display the updated value. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, matchmaking operations (create/join/leave gathering, vote, rating changes, etc.) are logged for monitoring and analysis. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentModelMaster Currently active Models master data This master data defines the Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Matchmaking Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentModelMaster Updated master data of the currently active Models Implementation Example RatingModel Rating Model GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value.  ratingModelId string * ~ 1024 chars Rating Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. SeasonModel Season Model Defines the season-specific settings for Season Matchmaking, including the period of persistent gatherings, maximum participant count, and tier integration settings. Managed by GS2-Schedule for period control, and can be linked with GS2-Experience for persistent gathering within the same tier as needed.  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management The GRN of the GS2-Experience experience model used to determine player tiers. The player’s rank within this experience model is used as their tier for matchmaking, ensuring players are grouped with others at a similar level. If not specified, tier-based grouping is disabled and all players are matched together regardless of level. challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Schedule event that defines the active period for this season. Season Gatherings can only be created and joined while this event is active. When the event period ends, the season closes and new matchmaking is no longer possible.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Matchmaking Deploy/CDK Reference","url":"/api_reference/matchmaking/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentFieldMaster Currently active Field Model master data This master data defines the Field Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-MegaField Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentFieldMaster Updated master data of the currently active Field Models Implementation Example AreaModel Area divides space, and different areas can be treated as different spaces even if they have the same coordinates.  areaModelId string * ~ 1024 chars Area Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Area Model name 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. layerModels List [] 0 ~ 1000 items List of layer models LayerModel Layers allow for multiple logical hierarchies within a single space. For example, it solves the problem of an Enemy being invisible in a space with a large number of characters. Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance.  layerModelId string * ~ 1024 chars Layer Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Layer Model name 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.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-MegaField Deploy/CDK Reference","url":"/api_reference/mega_field/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used when granting mission completion rewards. missionCompleteScript ScriptSetting Script to run when a mission is accomplished Script Trigger Reference - missionComplete counterIncrementScript ScriptSetting Script to run when the counter rises Script Trigger Reference - counterIncrement receiveRewardsScript ScriptSetting Script to run when a reward is received Script Trigger Reference - receiveRewards completeNotification NotificationSetting  Push notifications when mission tasks are accomplished Configures push notifications delivered via GS2-Gateway when a mission task’s completion conditions are met. This allows the game client to immediately reflect the accomplishment in the UI. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for debugging counter increments, mission completions, and reward receipts. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Created namespace Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentMissionMaster Currently active Mission Model master data This master data defines the Mission Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Mission Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentMissionMaster Updated master data of the currently active Mission Models Implementation Example CounterModel Counter Model Counter Model is an entity that can be set as a condition for accomplishing mission tasks. Since counter values can be referenced by multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions.  counterId string * ~ 1024 chars Counter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Specifies the GS2-Schedule event that defines the time window during which this counter can be incremented or decremented. If not set, the counter can be operated at any time. CounterScopeModel Counter Reset Timing Model Defines a scope for a counter, which determines how and when the counter value is reset. A scope can be either a reset timing (daily, weekly, monthly, fixed-day interval, or never) or a verify action condition. Each counter can have multiple scopes to track values across different periods.  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Determines how the counter scope is defined. “resetTiming” uses a periodic reset schedule, while “verifyAction” uses a verify action to determine whether the counter value applies. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the counter value for this scope is reset. Choose from: not reset (permanent cumulative), daily, weekly, monthly, or every fixed number of days. Only used when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the counter value resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the counter value resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the counter value resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name A unique name that identifies this verify action condition scope. Used to look up the corresponding scoped value in the counter. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” condition VerifyAction {scopeType} == “verifyAction”  Condition The verify action that determines whether the counter value for this scope is applicable. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between counter value resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” MissionGroupModel Mission Group Model A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission.  missionGroupId string * ~ 1024 chars Mission Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. tasks List [] 0 ~ 1000 items List of Mission Task The mission tasks belonging to this group. Each task defines a completion condition (counter threshold or verify actions) and the rewards granted upon accomplishment. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” MissionTaskModel Mission Task Model A mission task is an entity that defines the conditions under which a reward will be given if the value of the associated counter exceeds a certain level.  missionTaskId string * ~ 1024 chars Mission Task A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” [] 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received Specifies the GS2-Schedule event that defines the time window during which the mission task rewards can be claimed. If not set, rewards can be received at any time after accomplishment. premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. TargetCounterModel Target Counter Information about the counter that serves as the achievement goal for the mission  counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Specifies which type of counter scope to use for the mission completion check. “resetTiming” evaluates the counter value for a specific reset period, while “verifyAction” evaluates the value for a named condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming” Target Reset timing Specifies which reset timing scope of the counter to check against the target value. For example, selecting “daily” means the task checks the daily counter value. If omitted, the mission group’s reset timing is used. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Enabled only if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition scope to check against the target value. Must match a conditionName defined in the counter model’s scopes. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long  0 ~ 9223372036854775805 Target value The threshold value that the counter’s scoped value must reach or exceed for the mission task to be considered accomplished. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Mission Deploy/CDK Reference","url":"/api_reference/mission/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Settings Configuration for controlling how transactions are processed when executing money operations. priority string (enum) enum {   “free”,   “paid” }  Consumption Priority Determines the order in which paid and free currency is consumed when withdrawing from the wallet. When set to “free”, free currency (price=0) is consumed first, then paid currency from the highest unit price. When set to “paid”, paid currency is consumed first starting from the highest unit price, then free currency. Definition Description “free” Prioritize the use of free currency “paid” Prioritize the use of paid currency shareFree bool  Share Free Currency Whether free currency is shared across all wallet slots. When enabled, free currency balances are synchronized from slot 0 to all other slots, allowing players on different platforms to share the same free currency pool. Paid currency always remains separate per slot regardless of this setting. currency string (enum) enum {   “JPY”,   “USD”,   “TWD” }  Currency Type The real-world currency used for pricing and Funds Settlement Act compliance calculations. This determines the unit of measurement for tracking paid currency values and calculating refund obligations. Cannot be changed after namespace creation. Definition Description “JPY” JPY “USD” USD “TWD” TWD appleKey string ~ 1024 chars Apple AppStore Bundle ID The Bundle ID of your iOS app, used to verify Apple AppStore purchase receipts. Required when accepting in-app purchases from iOS devices. googleKey string ~ 5120 chars Google PlayStore Private Key The service account private key for Google Play, used to verify Google Play purchase receipts. Required when accepting in-app purchases from Android devices. enableFakeReceipt bool false Enable Fake Receipt Whether to accept fake purchase receipts generated by Unity Editor for testing purposes. Should only be enabled in development/test environments and must be disabled in production to prevent unauthorized currency grants. Defaults to false. createWalletScript ScriptSetting Create Wallet Script Script to run when a new wallet is created for the first time. Wallets are auto-created on first access, so this script triggers when a player first interacts with the currency system. depositScript ScriptSetting Deposit Script Script to run when currency is added to the wallet. Triggered for both paid currency deposits (from store purchases) and free currency grants. withdrawScript ScriptSetting Withdraw Script Script to run when currency is consumed from the wallet. Triggered when paid or free currency is deducted according to the consumption priority setting. logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, wallet operations (deposit, withdraw, purchase) are logged for monitoring, auditing, and analysis. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Money Deploy/CDK Reference","url":"/api_reference/money/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). currencyUsagePriority string (enum) enum {   “PrioritizeFree”,   “PrioritizePaid” }  Consumption priority Determines the order in which paid and free currency are consumed when withdrawing from the wallet. “PrioritizeFree” consumes free currency first, while “PrioritizePaid” consumes paid currency first. Definition Description “PrioritizeFree” Prioritize the use of free currency “PrioritizePaid” Prioritize the use of paid currency description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when depositing or withdrawing currency. sharedFreeCurrency bool  Share the free currency with different slots When enabled, free currency balance is shared across all wallet slots (platforms). Paid currency remains separate per slot. This setting can only be configured at namespace creation time and cannot be changed later. platformSetting PlatformSetting  Store platform settings Configuration for each supported store platform (Apple App Store, Google Play, Fake for testing). Includes credentials and keys required for receipt verification on each platform. depositBalanceScript ScriptSetting Script setting to be executed when depositing wallet balance Script Trigger Reference - deposit withdrawBalanceScript ScriptSetting Script setting to be executed when withdrawing wallet balance Script Trigger Reference - withdraw verifyReceiptScript ScriptSetting Script setting to be executed when verifying a receipt Script Trigger Reference - verifyReceipt subscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when subscribing to a new contract(Not called when the user associated with the subscription is changed / Called when re-subscribing after contract expiration) Script Trigger Reference - subscribe renewScript string ~ 1024 chars GS2-Script script GRN to be executed when renewing a contract Script Trigger Reference - renew unsubscribeScript string ~ 1024 chars GS2-Script script GRN to be executed when unsubscribing from a contract(Not called when the user associated with the subscription is changed) Script Trigger Reference - unsubscribe takeOverScript ScriptSetting Script setting to be executed when taking over a contract Script Trigger Reference - takeOver changeSubscriptionStatusNotification NotificationSetting Push notification when the subscription status changes Configures push notifications delivered via GS2-Gateway when a subscription status changes (e.g., activated, renewed, canceled, expired, or revoked). Allows the game client to respond to subscription state transitions in real-time. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace to which API request and response logs for this namespace will be output. Useful for tracking deposits, withdrawals, receipt verifications, and subscription events. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. PlatformSetting Platform Setting Aggregates the settings for all supported store platforms. Contains configuration for Apple App Store, Google Play, and Fake (for testing in Unity Editor). Each platform setting includes the credentials and keys necessary for receipt verification.  appleAppStore AppleAppStoreSetting Apple AppStore Setting Credentials for Apple App Store receipt verification, including bundle ID, shared secret key, issuer ID, key ID, and private key. googlePlay GooglePlaySetting Google Play Setting Credentials for Google Play receipt verification, including the package name and public key for signature verification. fake FakeSetting Fake (Unity Editor) Setting Configuration for accepting fake receipts generated by Unity Editor during development and testing. AppleAppStoreSetting Apple AppStore Setting Configuration for verifying Apple App Store receipts. Contains the credentials required to communicate with Apple’s receipt verification servers, including the bundle ID, shared secret, App Store Connect issuer ID, key ID, and private key.  bundleId string ~ 1024 chars Apple AppStore Bundle ID sharedSecretKey string ~ 1024 chars Shared secret key used to encrypt the receipt issued by AppStore Connect issuerId string ~ 1024 chars Issuer ID of in-app purchases registered with AppStore Connect keyId string ~ 1024 chars Key ID registered with Apple privateKeyPem string ~ 10240 chars Private Key received from Apple GooglePlaySetting Google Play Setting Configuration for verifying Google Play receipts. Contains the package name and public key required for validating purchase signatures from Google Play.  packageName string ~ 5120 chars Package Name to be distributed on Google Play publicKey string ~ 5120 chars Public key used for signature verification FakeSetting Fake Setting for Debug Configuration for handling fake receipts generated by Unity Editor during development. Controls whether fake receipts are accepted or rejected, allowing developers to test in-app purchase flows without real store platforms.  acceptFakeReceipt string (enum) enum {   “Accept”,   “Reject” } “Reject” Whether to allow payments using fake receipts output by Unity Editor Controls acceptance of fake receipts. Should be set to “Accept” during development/testing and “Reject” in production to prevent unauthorized currency deposits. Definition Description “Accept” Accept “Reject” Reject CurrentModelMaster Currently active Models master data This master data defines the Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Money2 Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentModelMaster Updated master data of the currently active Models Implementation Example StoreContentModel Store Content Model This is a model for storing content from various store platforms.  storeContentModelId string * ~ 1024 chars Store Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Content Model name metadata string ~ 1024 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. appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. AppleAppStoreContent Content of Apple AppStore Contains the Apple App Store product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Apple App Store product identifier registered in App Store Connect for this in-app purchase item. GooglePlayContent Content of Google Play Contains the Google Play product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Google Play product identifier registered in Google Play Console for this in-app purchase item. StoreSubscriptionContentModel Store Subscription Content Model This is a model for storing subscription-based content from various store platforms.  storeSubscriptionContentModelId string * ~ 1024 chars Subscription Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Subscription Content Model name metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Enabled only if triggerExtendMode is “rollupHour” reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. AppleAppStoreSubscriptionContent Subscription content of Apple AppStore Contains the Apple App Store subscription group identifier for subscription-based products. Used to manage and verify auto-renewable subscriptions.  subscriptionGroupIdentifier string ~ 64 chars Subscription Group ID The subscription group identifier registered in App Store Connect. Subscriptions within the same group are mutually exclusive, meaning a user can only subscribe to one at a time. GooglePlaySubscriptionContent Google Play Subscription Content Contains the Google Play product ID for subscription-based products. Used to manage and verify auto-renewable subscriptions on Google Play.  productId string ~ 1024 chars Product ID","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Money2 Deploy/CDK Reference","url":"/api_reference/money2/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description logSetting LogSetting Log Output Setting Configuration for outputting API request/response logs to GS2-Log. When configured, news operations (article retrieval, content generation, cookie issuance, etc.) are logged for monitoring and analysis. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-News Deploy/CDK Reference","url":"/api_reference/news/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when granting quest rewards. startQuestScript ScriptSetting Script setting to be executed when the quest is started Script Trigger Reference - startQuest completeQuestScript ScriptSetting Script setting to be executed when a quest is completed Script Trigger Reference - completeQuest failedQuestScript ScriptSetting Script to run when a quest fails Script Trigger Reference - failedQuest logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking quest start, completion, and failure events. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentQuestMaster Currently active Quest Model master data This master data defines the Quest Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Quest Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentQuestMaster Updated master data of the currently active Quest Models Implementation Example QuestGroupModel Quest Group Model A Quest Group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups.  questGroupModelId string * ~ 1024 chars Quest Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. quests List [] 0 ~ 1000 items Quests belonging to the group List of quest models that belong to this quest group. Only one quest within the group can be in progress at a time. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. QuestModel Quest Model A Quest Model is an entity that defines the cost required to start a quest and the rewards obtained upon completion. The reward obtained upon completion of the quest can have multiple variations and can be drawn at the start of the quest. For example, the same content can be used to manage the clear flag of a quest, but two types of content can be prepared based on whether or not a rare monster appears.  questModelId string * ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. contents List [] 1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. Contents Contents Represents one variation of quest content. Each quest can have multiple content variations with different rewards, and one is selected by weighted random draw at quest start. The metadata supports template variable substitution with user ID and config values.  metadata string ~ 256 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. completeAcquireActions List [] 0 ~ 10 items Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. weight int 1 1 ~ 2147483646 Draw Weight The relative weight used in the random selection of this content variation at quest start. Higher values increase the probability of this variation being selected. For example, a variation with weight 9 is 9 times more likely to be selected than one with weight 1. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Quest Deploy/CDK Reference","url":"/api_reference/quest/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing ranking operations. logSetting LogSetting Log Setting Configuration for outputting ranking-related operation logs to GS2-Log. When configured, actions such as score registration, ranking retrieval, and subscription changes are recorded for analysis and auditing. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentRankingMaster Currently active Ranking Model master data This master data defines the Ranking Models currently active within the namespace. Master data describing the currently valid ranking model definitions within the namespace GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Ranking Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example CategoryModel Category Model Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. Scope Aggregation Scope Defines an additional time-windowed aggregation scope for Global Ranking mode. Normally, global ranking is calculated for all registered scores regardless of when they were submitted. By adding scopes, you can create separate rankings that only consider scores registered within a specified number of days, enabling daily, weekly, or monthly leaderboards alongside the all-time ranking.  name string  ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. targetDays long  1 ~ 365 Target Days The number of days to include in the aggregation window. Only scores registered within this number of days from the current time are considered for the scoped ranking. Range: 1-365 days. GlobalRankingSetting Global Ranking Setting Global is a ranking where all players see the same results. The ranking interval can be set from 15 minutes to 24 hours. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  uniqueByUserId bool true Unique By User ID When enabled, only one score per user ID is kept in the ranking. If a user submits a new score, it replaces the previous one (keeping the better score based on the sort direction). When disabled, multiple score entries from the same user are allowed, enabling sum-mode or multi-entry competition. calculateIntervalMinutes int  15 ~ 1440 Calculate Interval Minutes The interval in minutes between successive ranking recalculations. The system periodically recalculates the global ranking based on all registered scores at this interval. Range: 15 to 1440 minutes (15 minutes to 24 hours). calculateFixedTiming FixedTiming Calculate Fixed Timing Specifies a fixed time of day (UTC) at which ranking recalculation starts. If not set, recalculation occurs at regular intervals from an unspecified base time. Setting this ensures recalculations happen at a predictable, consistent time each day. additionalScopes List 0 ~ 10 items Additional Scopes A list of additional time-windowed aggregation scopes. Each scope defines a separate ranking that only considers scores registered within a specified number of days. This enables creating daily, weekly, or monthly leaderboards alongside the all-time global ranking. Maximum 10 scopes. ignoreUserIds List 0 ~ 10000 items Ignore User IDs A list of user IDs whose scores should be excluded from ranking calculation. Useful for filtering out test accounts, administrator accounts, or known cheaters from the leaderboard. Maximum 10,000 entries. generation string ~ 256 chars Generation An arbitrary string representing the current ranking generation. Changing this value effectively resets all registered scores, as scores from a previous generation are no longer included in ranking calculations. Useful for implementing seasonal resets or periodic ranking resets. Maximum 256 characters. FixedTiming Fixed Timing Specifies the fixed time of day at which global ranking calculations start. Without this setting, ranking calculation occurs at regular intervals from an unspecified base time. By specifying a fixed hour and minute, you can ensure that ranking recalculation always begins at a predictable time (in UTC), such as midnight or a specific hour.  hour int 0 ~ 23 Hour The hour (UTC) at which ranking calculation starts. Specified as an integer from 0 to 23. minute int 0 ~ 59 Minute The minute at which ranking calculation starts within the specified hour. Specified as an integer from 0 to 59.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Ranking Deploy/CDK Reference","url":"/api_reference/ranking/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Settings for distributed transactions used to grant ranking rewards. Supports auto-run to automatically execute transactions and atomic commit for all-or-nothing guarantee. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking score submissions and ranking reward distributions. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentRankingMaster Currently active Ranking Model master data This master data defines the Ranking Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Ranking2 Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentRankingMaster Updated master data of the currently active Ranking Models Implementation Example GlobalRankingModel Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  globalRankingModelId string * ~ 1024 chars Global Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index RankingReward Ranking Reward Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.  thresholdRank int  1 ~ 1001 Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). metadata string ~ 1024 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. acquireActions List [] 0 ~ 100 items List of Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. ClusterRankingModel Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  clusterRankingModelId string * ~ 1024 chars Cluster Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index SubscribeRankingModel Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking.  subscribeRankingModelId string * ~ 1024 chars Subscribe Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Ranking2 Deploy/CDK Reference","url":"/api_reference/ranking2/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing realtime operations. serverType string (enum) enum {   “relay” }  Server Type The type of game server to provision for real-time communication. Currently supports “relay” mode, which provides a packet relay server that forwards messages between connected game clients. Definition Description “relay” Packet relay serverSpec string (enum) enum {   “realtime1.nano” }  Server Spec The hardware specification tier for the provisioned game server. Determines the compute resources (CPU, memory) allocated to each room’s server instance. Currently supports “realtime1.nano”. Definition Description “realtime1.nano” realtime1.nano createNotification NotificationSetting Create Notification Push Notification Setting triggered when a room finishes provisioning and is ready for connections. Since room creation is asynchronous (IP address, port, and encryption key are assigned after a short delay), this notification informs clients that the room is ready to accept connections. logSetting LogSetting Log Setting Configuration for outputting realtime-related operation logs to GS2-Log. When configured, actions such as room creation, connection events, and message relay activities are recorded for analysis and debugging. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions NotificationSetting Push Notification Setting Configuration for sending push notifications when events occur in GS2 microservices. The push notification here refers to the processing via the WebSocket interface provided by GS2-Gateway, and is different from the push notification of a smartphone. For example, when matchmaking is completed or a friend request is received, the GS2-Gateway can send a push notification via the WebSocket interface, and the game client can detect the change of the state. GS2-Gateway’s push notifications can be used to forward notifications to mobile push notification services when the destination device is offline. By properly utilizing mobile push notifications, you can implement a flow in which players are notified even if they exit the game during matchmaking and later return to it.  gatewayNamespaceId string “grn:gs2:{region}:{ownerId}:gateway:default” ~ 1024 chars GS2-Gateway namespace to use for push notifications Specify the GS2-Gateway namespace ID in GRN format starting with “grn:gs2:”. enableTransferMobileNotification bool? false Whether to forward the notification as a mobile push notification When an attempt is made to send this notification and the destination device is offline, specify whether it should be forwarded as a mobile push notification. sound string {enableTransferMobileNotification} == true ~ 1024 chars Sound file name to be used for mobile push notifications The sound file name specified here is used when sending mobile push notifications, and you can send notifications with a special sound. * Enabled only if enableTransferMobileNotification is true enable string (enum) enum {   “Enabled”,   “Disabled” } “Enabled” Whether to enable push notifications Definition Description “Enabled” Enabled “Disabled” Disabled LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Realtime Deploy/CDK Reference","url":"/api_reference/realtime/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing schedule operations. logSetting LogSetting Log Setting Configuration for outputting schedule-related operation logs to GS2-Log. When configured, actions such as event queries, trigger activation, and trigger deletion are recorded for analysis and auditing. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentEventMaster Currently active Event master data This master data defines the Events currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Schedule Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentEventMaster Updated master data of the currently active Event Implementation Example Event Event Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period.  eventId string * ~ 1024 chars GS2-Schedule Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Event name Event-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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. RepeatSetting Repeat Setting Configures a recurring time window within the overall event period. Supports five repeat types: “always” (entire event period), “daily” (specific hours each day), “weekly” (specific day-of-week range with hours), “monthly” (specific day-of-month range with hours), and “custom” (alternating active/inactive day cycles from an anchor date). When beginHour equals endHour for daily/weekly/monthly types, the end time is treated as the same hour on the following day (i.e., a full 24-hour window).  repeatType string (enum) enum {   “always”,   “daily”,   “weekly”,   “monthly”,   “custom” } “always” Repeat Type The type of repeat pattern to apply within the event period. Determines which additional fields are required: daily/weekly/monthly require hour settings, weekly requires day-of-week, monthly requires day-of-month, and custom requires anchor timestamp and day counts. Defaults to “always” if not specified. Definition Description “always” Always during the entire event period “daily” Every day during the event period from X:00 to X:00 “weekly” During the event period, every week from the start day to the end day, X:00 to X:00 “monthly” During the event period, every month from the start date to the end date, X:00 to X:00 “custom” Starting from the reference date, active for X days and inactive for Y days during the event period beginDayOfMonth int {repeatType} == “monthly”  1 ~ 31 Begin Day of Month The day of the month when the repeat window starts (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” endDayOfMonth int {repeatType} == “monthly”  1 ~ 31 End Day of Month The day of the month when the repeat window ends (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” beginDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  Begin Day of Week The day of the week when the repeat window starts. The window can span across week boundaries (e.g., Friday to Monday). Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” endDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  End Day of Week The day of the week when the repeat window ends. Combined with beginDayOfWeek to define the weekly active period. Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” beginHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 23 Begin Hour The hour (UTC, 0-23) at which the repeat window starts each cycle. Required for daily, weekly, and monthly repeat types. If beginHour equals endHour, the window spans a full 24 hours (ending at the same hour the next day). * Required if repeatType is “daily”,“weekly”,“monthly” endHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 24 End Hour The hour (UTC, 0-24) at which the repeat window ends each cycle. A value of 24 represents midnight of the following day. Required for daily, weekly, and monthly repeat types. * Required if repeatType is “daily”,“weekly”,“monthly” anchorTimestamp long {repeatType} == “custom”  Anchor Timestamp The reference date from which the custom active/inactive cycle begins. The system calculates which phase (active or inactive) the current time falls into based on elapsed days from this anchor. Only applicable when repeatType is “custom”. Expressed as Unix time in milliseconds. * Required if repeatType is “custom” activeDays int {repeatType} == “custom”  1 ~ 2147483646 Active Days The number of consecutive days the event is active in each custom cycle. After these active days, the event becomes inactive for the number of days specified by inactiveDays, then the cycle repeats. Only applicable when repeatType is “custom”. Minimum 1 day. * Required if repeatType is “custom” inactiveDays int {repeatType} == “custom”  0 ~ 2147483646 Inactive Days The number of consecutive days the event is inactive in each custom cycle. Follows the active days period. Set to 0 for a continuously active event with no gaps. Only applicable when repeatType is “custom”. Minimum 0 days. * Required if repeatType is “custom”","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Schedule Deploy/CDK Reference","url":"/api_reference/schedule/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Settings for distributed transactions used when scripts return transaction actions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request and response logs. Used for tracking script invocations and their results. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. Script Script GS2 provides scripts to extend functionality when the standard functions are not sufficient. Scripts can be written in the Lua language. Scripts can also retrieve data from GS2 services, allowing for flexible processing. Please refer to the documentation for details. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). name string  ~ 128 chars Script name Script-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description script string  ~ 5242880 chars Lua Script disableStringNumberToNumber bool false Do not convert strings consisting only of numbers to numbers GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Script Script created Implementation Example","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Script Deploy/CDK Reference","url":"/api_reference/script/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when applying season rating results. logSetting LogSetting Log Output Setting Configuration for logging season rating operations such as ballot issuance, vote submissions, and rating calculations. When set, operation logs are output to the specified GS2-Log namespace. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAtomicCommit bool false Whether to commit the execution of transactions atomically transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentSeasonModelMaster Currently active Season Model master data This master data defines the Season Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SeasonRating Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentSeasonModelMaster Updated master data of the currently active Season Models Implementation Example SeasonModel Season Model Defines the tier structure and point adjustment rules applied during a season. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience.  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. TierModel Tier Model TierModel defines the point adjustment rules for each tier within a season. Specifies point change ranges by rank, entry fees, and promotion bonuses. While actual point data is managed by GS2-Experience, the calculation logic for point adjustments is determined by the TierModel configuration.  metadata string ~ 128 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. raiseRankBonus int  0 ~ 10000 Raise Rank Bonus Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion. For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold. Valid range: 0 to 10000. entryFee int  0 ~ 10000 Entry Fee Points deducted from the player before the match begins as a participation cost. This fee is always subtracted regardless of the match outcome, creating a risk element in competitive play. Valid range: 0 to 10000. minimumChangePoint int  -99999999 ~ -1 Minimum Change Point The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss. Must be a negative value. The actual point change for a losing player falls between this value and 0. Valid range: -99999999 to -1. maximumChangePoint int  1 ~ 99999999 Maximum Change Point The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win. Must be a positive value. The actual point change for a winning player falls between 0 and this value. Valid range: 1 to 99999999.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-SeasonRating Deploy/CDK Reference","url":"/api_reference/season_rating/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing serial key operations. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to serial code issuance and usage. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Manages log output setting. This type holds the identifier of the log namespace used to output log data. The log namespace ID specifies the GS2-Log namespace to aggregate and store the log data. Through this setting, API request and response log data under this namespace will be output to the target GS2-Log. GS2-Log provides logs in real time, which can be used for system monitoring, analysis, debugging, etc.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentCampaignMaster Currently active Campaign Model master data This master data defines the Campaign Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SerialKey Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update the master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentCampaignMaster Updated master data of the currently active Campaign Models Implementation Example CampaignModel Campaign Model A Campaign Model is used to define and manage campaigns, linking them to serial codes.  campaignId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Campaign Model * Set automatically by the server name string  ~ 128 chars Campaign Model name 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-SerialKey Deploy/CDK Reference","url":"/api_reference/serial_key/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Setting Configuration for controlling how transactions are processed when executing showcase operations. buyScript ScriptSetting Script to run when attempting to execute a purchase Script Trigger Reference - buy logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to showcase browsing and product purchases. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentShowcaseMaster Currently active Showcase Model master data This master data defines the Showcase Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Showcase Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentShowcaseMaster Updated master data of the currently active Showcase Implementation Example Showcase Showcase A Showcase can define items for display. Additionally, the sales period for items on Showcase can be set.  showcaseId string * ~ 1024 chars Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Showcase name Showcase-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. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Controls the overall sales period of this showcase. When specified, the entire showcase is only available during the associated GS2-Schedule event period. If the event is not active, the showcase returns empty. displayItems List [] 1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. DisplayItem Displayed Item An item displayed on a showcase. Can reference either a single sales item or a sales item group. Each display item can have its own sales period controlled by a GS2-Schedule event, independently of the showcase-level sales period.  displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. type string (enum) enum {   “salesItem”,   “salesItemGroup” }  Type The type of item displayed. A “salesItem” is a single Sales Item with fixed price and rewards. A “salesItemGroup” contains multiple Sales Items evaluated in order, used for step-up pricing or limited purchase discounts. Definition Description “salesItem” Sales Item “salesItemGroup” Sales Item Group salesItem SalesItem {type} == “salesItem”  Sales Item * Required if type is “salesItem” salesItemGroup SalesItemGroup {type} == “salesItemGroup”  Sales Item Group * Required if type is “salesItemGroup” salesPeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with sales periods for this display item Controls the sales period of this individual display item. When specified, the item is only shown on the showcase during the associated GS2-Schedule event period. This is independent of the showcase-level sales period. SalesItem Sales Item Defines the price required to purchase a Sales Item and the rewards granted upon purchase.  name string  ~ 128 chars Sales Item name Sales Item-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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. SalesItemGroup Sales Item Group A Sales Item Group is an entity for display on a Showcase. Multiple Sales Items can belong to a Sales Item Group. Sales Items are evaluated in order, and the first Sales Item determined to be available for purchase is displayed on the Showcase. This can be used for Sales Items that are discounted only for the first purchase, or for systems where the contents change based on the number of purchases, such as a step-up gacha.  name string  ~ 128 chars Sales Item Group name Sales Item Group-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. salesItems List [] 2 ~ 10 items Sales Items included in the Sales Item Group Ordered list of sales items in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. RandomShowcase Random Showcase Random Showcase is a display model featuring randomly selected display items that rotate at specified intervals. The display item to be selected are randomly selected from the registered display items in the display item pool according to the specified quantity and the weight set for each display item. By associating a GS2-Schedule event with the Random Showcase, you can set its sales period.  randomShowcaseId string * ~ 1024 chars Random Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Random Showcase name Random Showcase-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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List [] 1 ~ 100 items List of Display Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Controls the overall sales period of this random showcase. When specified, the showcase is only available during the associated GS2-Schedule event period. RandomDisplayItemModel Items that can be displayed in a Random Showcase You can set the probability of selecting each item with weight .  name string  UUID ~ 128 chars Random Displayed Item ID Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before purchasing this Random Displayed Item. All verify actions must pass before consume and acquire actions are processed. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price for this Random Displayed Item. Executed as consume actions in the transaction. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards for this Random Displayed Item. Executed as acquire actions in the transaction. stock int  1 ~ 2147483646 Stock The maximum number of times this item can be drawn across all rotations. Once stock reaches zero, the item is excluded from future draws. Stock is consumed when the item is selected during a rotation draw. weight int  1 ~ 2147483646 Draw Weight The relative probability weight for this item in the random selection. Higher weights increase the chance of being drawn. The actual selection probability is calculated as this item’s weight divided by the sum of all eligible items’ weights. ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Showcase Deploy/CDK Reference","url":"/api_reference/showcase/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting  Transaction Settings Configuration for transaction processing used when executing node release and restrain operations. Defines how consume actions (release costs) and acquire actions (restrain refunds) are processed through the GS2 transaction system. releaseScript ScriptSetting Script to run when a node is released Script Trigger Reference - release restrainScript ScriptSetting Script to run when a node is restrained Script Trigger Reference - restrain logSetting LogSetting Log Output Setting Configuration for logging skill tree operations such as node releases, restrains, and resets. When set, operation logs are output to the specified GS2-Log namespace. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentTreeMaster Currently active Node Model master data This master data defines the Node Models currently active within the Namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-SkillTree Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentTreeMaster Updated master data of the currently active Node Models Implementation Example NodeModel Node Model Defines a node within the skill tree, including its unlock cost, prerequisites, and refund behavior. Each node can have verify actions (conditions to check before release), consume actions (costs to pay), and prerequisite nodes that must be released first. When a node is restrained (reverted to unreleased), the consumed resources are partially refunded based on the restrain return rate. The return acquire actions are automatically calculated from the consume actions multiplied by the restrain return rate.  nodeModelId string * ~ 1024 chars Node Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Node Model name Node 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. releaseVerifyActions List [] 0 ~ 10 items List of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. returnAcquireActions List 0 ~ 10 items Return Acquire Actions List of acquire actions executed when restraining (reverting) this node, representing the resources returned to the player. This field is auto-generated from the release consume actions multiplied by the restrain return rate. For example, if release costs 100 gold and the return rate is 0.8, restraining returns 80 gold. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-SkillTree Deploy/CDK Reference","url":"/api_reference/skill_tree/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing stamina operations. overflowTriggerScript string ~ 1024 chars Overflow Trigger Script GRN of a GS2-Script to invoke when stamina overflows during recovery. This script is triggered when time-based recovery would push stamina above the maximum value, allowing custom handling of the excess (e.g., converting overflow to items). Script Trigger Reference - overflow logSetting LogSetting Log Output Setting Configuration for logging stamina-related operations such as consume, recover, and overflow events to GS2-Log. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentStaminaMaster Currently active Stamina Model master data This master data defines the Stamina Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Stamina Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentStaminaMaster Updated master data of the currently active Stamina Models Implementation Example StaminaModel Stamina Model Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience.  staminaModelId string * ~ 1024 chars Stamina Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. For example, if initialCapacity is 100 and maxCapacity is 200, items can boost stamina up to 200 but natural recovery stops at 100. * Required if isOverflow is true maxStaminaTable MaxStaminaTable Max Stamina Table Reference to a MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. If not set, all players share the same initialCapacity as their maximum. recoverIntervalTable RecoverIntervalTable Recover Interval Table Reference to a RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table using their current rank index, overriding recoverIntervalMinutes. If not set, all players share the same recoverIntervalMinutes. recoverValueTable RecoverValueTable Recover Value Table Reference to a RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table using their current rank index, overriding recoverValue. If not set, all players share the same recoverValue. MaxStaminaTable Maximum Stamina Table This entity defines the maximum value of stamina for each rank of GS2-Experience.  name string  ~ 128 chars Maximum Stamina Table Name Maximum Stamina Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. RecoverIntervalTable Recovery Interval Table This entity defines the stamina recovery interval for each rank of GS2-Experience.  name string  ~ 128 chars Stamina recovery interval table name Stamina recovery interval table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. RecoverValueTable Stamina Recovery Amount Table This entity defines the amount of stamina recovery for each rank of GS2-Experience.  name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Stamina Deploy/CDK Reference","url":"/api_reference/stamina/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description supportSpeculativeExecution string (enum) enum {   “enable”,   “disable” } “disable” Whether to support speculative execution When enabled, state machine definitions and random status are embedded in the Status entity, allowing clients to simulate state transitions locally before server confirmation. Requires transactionSetting to be configured. Definition Description “enable” Enable “disable” Disable transactionSetting TransactionSetting {supportSpeculativeExecution} == “enable” Transaction Settings Configuration for controlling how transactions are processed when executing state machine emit actions. Required when speculative execution is enabled. * Enabled only if supportSpeculativeExecution is “enable” startScript ScriptSetting Script to execute when starting the state machine Script Trigger Reference - start passScript ScriptSetting Script to execute when the state machine is successfully completed Script Trigger Reference - pass errorScript ScriptSetting Script to execute when the state machine fails Script Trigger Reference - error lowestStateMachineVersion long Lowest version of the state machine The minimum acceptable version for running state machines. Status instances created with a state machine version older than this value will be rejected, ensuring all running instances use up-to-date definitions. logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to state machine execution, state transitions, and emit events. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Settings Transaction Settings control how transactions are executed, their consistency, asynchronous processing, and conflict avoidance mechanisms. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN to be executed upon completion Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts Used when you want to know the completion of the done script. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. StateMachineMaster State machine definition Manages state machines written in GSL. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mainStateMachineName string  ~ 128 chars Main state machine name The name of the entry-point state machine in the GSL definition. Execution begins from this state machine, which can call sub-state machines via the stack mechanism. payload string  ~ 5242880 chars State machine definition The GSL (GS2 State Language) source code that defines the state machine’s states, transitions, and actions. Stored separately from the metadata for efficient retrieval. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item StateMachineMaster Created State Machine Master Implementation Example","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-StateMachine Deploy/CDK Reference","url":"/api_reference/state_machine/deploy/"},{"content":"Entities Resources managed by the Deploy operation Namespace Namespace A Namespace allows multiple independent instances of the same service within a single project by separating data spaces and usage contexts. Each GS2 service is managed on a per-namespace basis. Even when using the same service, if the namespace differs, the data is treated as a completely independent data space. Therefore, you must create a namespace before you can start using each service. Request Resource creation and update requests  name string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description transactionSetting TransactionSetting Transaction Setting Configuration for controlling how transactions are processed when executing version check operations. assumeUserId string  ~ 1024 chars GS2-Identifier user A unique resource name assigned to all information handled by GS2\" \u003e GRN to be promoted if the version check is passed acceptVersionScript ScriptSetting Script to run when a version is accepted/approved Script Trigger Reference - acceptVersion checkVersionTriggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to perform version checking process logSetting LogSetting Log Output Setting Specifies the GS2-Log namespace for outputting API request/response logs related to version checks and version approval operations. GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item Namespace Namespace created Implementation Example TransactionSetting Transaction Setting Transaction Setting controls execution methods, consistency, asynchronous processing, and conflict avoidance mechanisms of transactions. Combining features like AutoRun, AtomicCommit, asynchronous execution using GS2-Distributor, batch application of script results, and asynchronous processing of Acquire Actions via GS2-JobQueue enables robust transaction management tailored to game logic.  enableAutoRun bool false Whether to automatically execute issued transactions on the server side enableAtomicCommit bool {enableAutoRun} == true false Whether to commit the execution of transactions atomically * Enabled only if enableAutoRun is true transactionUseDistributor bool {enableAtomicCommit} == true false Whether to execute transactions asynchronously * Enabled only if enableAtomicCommit is true commitScriptResultInUseDistributor bool {transactionUseDistributor} == true false Whether to execute the commit processing of the script result asynchronously * Enabled only if transactionUseDistributor is true acquireActionUseJobQueue bool {enableAtomicCommit} == true false Whether to use GS2-JobQueue to execute the acquire action * Enabled only if enableAtomicCommit is true distributorNamespaceId string “grn:gs2:{region}:{ownerId}:distributor:default” ~ 1024 chars GS2-Distributor Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions queueNamespaceId string “grn:gs2:{region}:{ownerId}:queue:default” ~ 1024 chars GS2-JobQueue Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN used to execute transactions ScriptSetting Script Setting In GS2, you can associate custom scripts with microservice events and execute them. This model holds the settings for triggering script execution. There are two main ways to execute a script: synchronous execution and asynchronous execution. Because synchronous execution blocks processing until the script finishes executing, you can use the script result to stop the API execution or control the API response. In contrast, asynchronous execution does not block processing until the script has finished executing. However, because the script result cannot be used to stop the API execution or modify the API response, asynchronous execution does not affect the API response flow and is generally recommended. There are two types of asynchronous execution methods: GS2-Script and Amazon EventBridge. By using Amazon EventBridge, you can write processing in languages other than Lua.  triggerScriptId string ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN executed synchronously when the API is executed Must be specified in GRN format starting with “grn:gs2:”. doneTriggerTargetType string (enum) enum {   “none”,   “gs2_script”,   “aws” } “none” How to execute asynchronous scripts Specifies the type of script to use for asynchronous execution. You can choose from “Do not use asynchronous execution (none)”, “Use GS2-Script (gs2_script)”, and “Use Amazon EventBridge (aws)”. Definition Description “none” None “gs2_script” GS2-Script “aws” Amazon EventBridge doneTriggerScriptId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN for asynchronous execution Must be specified in GRN format starting with “grn:gs2:”. * Enabled only if doneTriggerTargetType is “gs2_script” doneTriggerQueueNamespaceId string {doneTriggerTargetType} == “gs2_script” ~ 1024 chars GS2-JobQueue namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to execute asynchronous execution scripts If you want to execute asynchronous execution scripts via GS2-JobQueue instead of executing them directly, specify the GS2-JobQueue namespace GRN. There are not many cases where GS2-JobQueue is required, so you generally do not need to specify it unless you have a specific reason. * Enabled only if doneTriggerTargetType is “gs2_script” LogSetting Log Output Setting Log Output Setting defines how log data is exported. This type holds the GS2-Log namespace identifier (Namespace ID), which is used to export log data. Specify the GS2-Log namespace where log data is collected and stored in the GRN format for the Log Namespace ID (loggingNamespaceId). Configuring this setting ensures that log data for API requests and responses occurring within the specified namespace is output to the target GS2-Log namespace. GS2-Log provides real-time logs that can be used for system monitoring, analysis, debugging, and other operational purposes.  loggingNamespaceId string  ~ 1024 chars GS2-Log namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to output logs Must be specified in GRN format starting with “grn:gs2:”. CurrentVersionMaster Currently active Version Model master data This master data defines the Version Models currently active within the namespace. GS2 uses JSON format files for managing master data. By uploading these files, the master data are updated on the server. To create JSON files, GS2 provides a master data editor within the management console. Additionally, you can create tools better suited for game operations and export JSON files in the appropriate format. Note Please refer to GS2-Version Master Data Reference for the JSON file format. Request Resource creation and update requests  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). mode string (enum) enum {   “direct”,   “preUpload” } “direct” Update mode Definition Description “direct” Directly update master data “preUpload” Upload master data and then update settings string {mode} == “direct”  ~ 5242880 chars Master Data * Required if mode is “direct” uploadToken string {mode} == “preUpload”  ~ 1024 chars Token obtained by pre-upload Used to apply the uploaded master data. * Required if mode is “preUpload” GetAttr Resource creation results that can be retrieved using the !GetAttr tag Type Description Item CurrentVersionMaster Updated master data of the currently active Version Models Implementation Example VersionModel Version Model You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version.  versionModelId string * ~ 1024 chars Version Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Version Model name Version 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Enabled only if scope is “active” Version Version Represents a version number with a three-level hierarchy (major, minor, micro). Version comparison is performed hierarchically: major version is compared first, then minor, then micro. Used to define warning and error thresholds for version checking.  major int  0 ~ 2147483646 Major version The highest priority component in version comparison. A difference in major version takes precedence over minor and micro versions. minor int  0 ~ 2147483646 Minor version The second priority component in version comparison. Compared only when the major versions are equal. micro int  0 ~ 2147483646 Micro version The lowest priority component in version comparison. Compared only when both major and minor versions are equal. ScheduleVersion Version that switches in chronological order Defines a set of version thresholds (current, warning, error) that become active during a specific time period controlled by a GS2-Schedule event. Multiple schedule versions can be configured to implement gradual version enforcement, such as warning users before blocking outdated clients.  currentVersion Version  Current Version The latest version available during this schedule period. Used with “active” scope to inform users of the current version when approving updates. warningVersion Version  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification during this schedule period. Login is allowed but the user is prompted to upgrade. errorVersion Version  Version that is determined to be an error by the version check The minimum version threshold for allowing login during this schedule period. If the client’s version is below this value, the version check results in an error and login is blocked. scheduleEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that enables version check Specifies the GS2-Schedule event that controls when this set of version thresholds is active. The version check configuration defined here only applies during the period when the specified event is active.","lang":"en","section":"api_reference","summary":"The template format used when creating stacks with GS2-Deploy, and implementation examples of template output in various languages using CDK\n","title":"GS2-Version Deploy/CDK Reference","url":"/api_reference/version/deploy/"},{"content":"This section explains the minimum implementation for creating an account and logging in using the GS2 SDK. For complete code for each platform, please check the Full Sample Code . About Implementation in Unity The Unity SDK uses Coroutines for asynchronous processing. The following code examples are intended to be executed within a Coroutine (a method that returns IEnumerator ). Initialize GS2 SDK Setup variables First, three variables are defined. Variable name Usage Source of acquisition clientId authentication information to access GS2 value created in Create credential (API key) clientSecret authentication information for accessing GS2 value created by create credential (API key) accountNamespaceName the namespace name of the GS2-Account to be used the value created in Prepare resources required for login process Setup general setting CreateFuture(Gs2Client.CreateAsync when using UniTask) to create a GS2 client. If clientId or clientSecret is incorrect, an error is returned here. Create GS2 client Initialize a GS2 client. If clientId or clientSecret is incorrect, an error will be returned here. Create new anonymous account Here we are creating an account to identify the game player. accountNamespaceName is the name of the namespace to which the account will be added. In this sample, a new account is created at every startup, but normally, an account is created only at the first startup of the application. The actual application saves this response account information in local storage, etc., and logs in as an existing game player using the created account information retrieved from local storage, etc., from the second time onward. Login process Next is the GS2 login process. Specify information on account authentication in Gs2AccountAuthenticator. Specifically, the namespace name of the GS2-Account to be used for login is specified. Furthermore, userId password specifies the user ID and password of the created account. The resulting GameSession object is returned. From now on, when calling GS2 APIs, GameSession will be passed as an argument for APIs that can only be called if the user is logged in. Calling APIs that can be called after login As an example of an API that can only be used while logged in, we call the API to get a list of takeover settings. You can pass GameSession to get a list of handover settings set for the currently logged-in game player. GS2 SDK termination process Terminate the connection with GS2. Have you completed the tutorial? [Check out our YouTube channel for guidance on how to use GS2!] (/articles/sample/youtube/) [We also provide more practical examples] (/articles/sample/project/) find out what else you can achieve with GS2 learn about the development workflow using GS2","lang":"en","section":"get_start","summary":"Let's implement from account issuance to login\n","title":"Implementation","url":"/get_start/tutorial/coding/"},{"content":"The GS2 game-engine SDKs (GS2 SDK for Unity, GS2 SDK for Unreal Engine, and so on) have a built-in cache that keeps data fetched from the server inside the SDK. Understanding this cache helps you reduce the number of API calls and improves both responsiveness and cost. Basic behavior When you fetch data through a Domain object (an access pattern such as gs2.Inventory.Namespace(...).Me(...).Inventory(...) ), the fetched data is stored in the SDK’s internal cache. Subsequent reads for the same resource are served from the cache without sending a request to the server. You can therefore look up the same value through Domain objects as many times as you need throughout your UI without re-fetching it from the server each time. Automatic cache refresh When data is updated on the server, the SDK cache is automatically updated to stay in sync. The cache is refreshed at the following times: When resource information is included in an API response received by the SDK When an update notification for a resource is delivered over a WebSocket connection When resource information is returned as the result of a stamp sheet execution For example, when an item is purchased through Gs2-Showcase , the increase of the corresponding Gs2-Inventory item count carried in the response of the purchase API is automatically reflected in the SDK cache. There is no need for the UI side to manually “re-fetch the inventory list”. Design guidelines Don’t hesitate to call read APIs Read operations performed through Domain objects, such as ModelAsync / Model / Fetch , will issue a request to the server on the first call and serve subsequent calls from the cache. As a result, even if your UI reads a value every time it redraws, this will not lead to excessive request charges. // Even if called on every UI redraw, calls after the first one are served from the SDK cache var item = await gs2.Inventory.Namespace(\"namespace-0001\") .Me(GameSession) .Inventory(\"inventory-0001\") .ItemSet(\"item-0001\") .ModelAsync(); Subscribe to cache updates Domain objects expose an event mechanism that lets you observe when the SDK’s internal cache is updated. By subscribing to these events from your UI, you can reflect changes such as item count updates without polling. For details, see the reference of each game-engine SDK. When you must read straight from the server The low-level APIs (those invoked directly through Gs2*RestClient / Gs2*WebSocketClient ) always send a request to the server and bypass the cache. Use these low-level APIs when you must guarantee that you see the latest state on the server, such as for server-side re-validation against cheating. Behavior during zone failover A GS2 region is composed of multiple zones running in an Active / Active configuration (see Region ). Because there is a slight replication delay between zones, you may experience a brief moment after a zone switch where “a value that was supposedly written cannot be read back”. The SDK cache is designed so that a UI does not get stuck on a stale value through such transient inconsistencies; it keeps up with the latest state on a best-effort basis. The cache converges to the latest values in the new zone without any extra work from the game developer. Related topics Region Cost Optimization","lang":"en","section":"articles","summary":"How the GS2 SDK caches data internally and design guidelines for taking advantage of it\n","title":"SDK Cache Mechanism","url":"/articles/tech/cache/"},{"content":"Many of today’s server systems present several challenges when it comes to verification. Setting up the environment for verification elements Time verification Server load verification Set up environment for validation items The infrastructure used for validation does not provide direct benefits. Therefore, the cost of maintaining the environment tends to be seen as a problem. The result is a poor validation environment that can lead to inefficient operations. GS2 uses a pay-as-you-go billing model, which means that there is no cost if the environment is not used, even if it is expanded. In addition, the environment can be set up and ready to use with GS2-Deploy. These features make it possible to increase or decrease the number of environments depending on the validation items. Specifically, if you want to perform the following validations, you need to perform the validation work in series in the conventional development style, but with GS2, you can perform the work in parallel. Verify that the one quest challenge per day limit works properly. Verify that quest drop rewards are appropriate. The example above shows a situation where a limit on the number of times a quest can be attempted makes it difficult to verify the content of drop rewards. In such a case, a version without the limit can be prepared in a different environment, and the drop rewards can be verified there. If the cost of preparing a separate environment is high, this decision cannot be made, and the time required for validation will increase. Time-related validation Validating that an event starts at a specific time is another challenging issue. Time-based processing is difficult to detect errors and, if possible, we would like to standardize the GS2 Deploy template applied to the production environment without accelerating the time period of the event in the validation environment. GS2 provides a mechanism to specify a time offset for time-based processing. If you are using GS2-Account, you can specify a different offset for each account, If you are using GS2-Auth to issue access tokens, you can specify the offset as a parameter when the access token is issued. With this feature, an account or access token with an offset of +2 weeks can be used to QA an event that occurs in 2 weeks by validating it with an account or access token with an offset of +2 weeks. This feature allows you to perform validation without changing the GS2-Schedule event period. Validation of server load Before inviting players to the server, it is necessary to check the server load to make sure that the service can be provided without problems even if a large number of players come to play. Since many games have server systems that have not been used in the past, this validation must be done carefully. However, GS2 hosts a large number of games, and GS2’s architecture has been verified to handle over 100,000 API requests per second. Therefore, GS2 users should not be concerned about server load. However, if you are really concerned, you can request a load test report from GS2 for a fee. The process is very simple. Play for an hour or so, preferably with 10 or more people, the equivalent of what a typical game player would play. You tell GS2 the GS2 account ID you used for the game, the project name and time of day, and the expected CCUs. GS2 creates a test scenario based on the access history, increases the number of accesses to match the CCU, and generates a report. If you have ever done load testing, you will understand how simple this process is.","lang":"en","section":"overview","summary":"How to quality assurance games using GS2.\n","title":"Verification","url":"/overview/workflow/qa/"},{"content":"Master Data Format  version string  2024-07-30 Format version of master data takeOverTypeModels List ~ 1000 items TakeOver Type Model This model defines TakeOver Information. TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately. Models TakeOverTypeModel TakeOver Type Model This model defines TakeOver Information. TakeOver Information is used when changing devices or moving/sharing an account across platforms. It consists of a unique string that identifies an individual and a password; by entering the correct combination, an Account (GS2 anonymous account) can be retrieved. Multiple sets of TakeOver Information can be configured for a single Account. To configure multiple sets, you must assign each one to a different slot. Slots can be specified from 0 to 1024, allowing for up to 1,025 types of TakeOver Information to be set. A typical example would be to store the account information for “Sign in with Apple” in slot 0 and the information for a Google account in slot 1. It should be noted that this TakeOver Information serves only as a container for data; the authentication mechanism for social accounts must be prepared separately.  takeOverTypeModelId string * ~ 1024 chars Takeover Type Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server type int  0 ~ 1024 Slot Number Specified in the range of 0 to 1024 to distinguish different types of TakeOver Information. 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. openIdConnectSetting OpenIdConnectSetting  OpenID Connect Configuration Configuration for integrating with an OpenID Connect-compliant Identity Provider (IdP). Includes the discovery URL, client credentials, and platform-specific settings such as Apple Sign In parameters. OpenIdConnectSetting OpenID Connect Configuration By registering the settings of an OpenID Connect-compliant IdP, IdP integration can be configured and used as TakeOver Information.  configurationPath string  ~ 1024 chars OpenID Connect Configuration URL The discovery endpoint URL of the OpenID Connect provider. Must follow the well-known format (e.g., https://example.com/.well-known/openid-configuration). clientId string  ~ 1024 chars Client ID The client ID of the application registered with the IdP. clientSecret string {configurationPath} != “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Client Secret * clientSecret is required when the configurationPath is not “https://appleid.apple.com/.well-known/openid-configuration”, i.e., for other IdP integrations. appleTeamId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Team ID of Apple Developer The team ID from the Apple Developer account. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” appleKeyId string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 1024 chars Key ID registered with Apple The key ID registered in the Apple Developer account for Sign in with Apple. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” applePrivateKeyPem string {configurationPath} == “https://appleid.apple.com/.well-known/openid-configuration”  ~ 10240 chars Private Key received from Apple The private key in PEM format downloaded from the Apple Developer portal. Required for Apple Sign In authentication. * Required if configurationPath is “https://appleid.apple.com/.well-known/openid-configuration” doneEndpointUrl string ~ 1024 chars Redirect URL after authentication is completed If not specified, it will transition to /authorization/done. id_token is attached to the Query String. additionalScopeValues List [] 0 ~ 10 items Additional scopes obtained with OpenID Connect Additional OAuth scopes to request from the IdP beyond the default OpenID Connect scopes. Allows retrieving extra user information during authentication. additionalReturnValues List [] 0 ~ 10 items Additional values returned from OpenID Connect Additional claim names from the ID token or UserInfo response to include in the return values. Specified claims are extracted and returned alongside the standard authentication result. ScopeValue Scope Value A key-value pair representing an additional OAuth scope value obtained during OpenID Connect authentication. Used to store extra data retrieved from the IdP beyond the standard OpenID Connect claims.  key string  ~ 64 chars Name The scope name that was requested from the IdP during authentication. value string ~ 51200 chars Value The value returned by the IdP for the corresponding scope.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Account Master Data Reference","url":"/api_reference/account/master_data/"},{"content":"Master Data Format  version string  2024-04-15 Format version of master data buffEntryModels List ~ 100 items Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period. Models BuffEntryModel Buff Entry Model The amount of buff is managed by BuffEntryModels, and multiple Buff Entry Models can be associated with the same target. The application order of BuffEntryModel is managed by the priority of BuffEntryModel, and the smaller the value of priority , the higher the priority . Three buff application methods exist: “Rate Add”, “Mul”, and “Value Add”. Rate Add is an instruction that adds to the buff application rate. Mul multiplies the current application rate by the specified value. Value Add is an instruction that adds to the value after buff correction calculations. For example, if the default rate is 1.0 and Rate Add 0.2 is set, the buff application rate becomes 1.2. Setting Mul 0.5 reduces the buff application rate to 0.5 times. BuffEntryModel can be associated with events of GS2-Schedule, and it is possible to set to apply buffs only during the event period.  buffEntryModelId string * ~ 1024 chars Buff Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Buff Entry Model name Buff Entry 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. expression string (enum) enum {   “rate_add”,   “mul”,   “value_add” }  Application type of buff Specifies how the buff value is applied to the target. “Rate Add” adds to the adjustment rate (e.g., 1.0 + 0.2 = 1.2), “Mul” multiplies the adjustment rate (e.g., rate * 0.5), and “Value Add” directly adds a value after rate-based correction calculations. Definition Description “rate_add” Add to adjustment rate “mul” Multiply the adjustment rate by the specified value “value_add” Directly add values (only numerical values for models or actions) targetType string (enum) enum {   “model”,   “action” }  Type of target to apply buff Specifies whether the buff is applied to a model’s field value or to an action’s parameter. “Model” targets a field on a GS2 resource model, while “Action” targets a parameter of a GS2 action (e.g., acquire or consume amounts). Definition Description “model” Model “action” Action targetModel BuffTargetModel {targetType} == “model”  Model to apply buff Specifies the target GS2 resource model and field to which the buff is applied. Includes the model name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “model” targetAction BuffTargetAction {targetType} == “action”  Action to apply buff Specifies the target GS2 action and parameter to which the buff is applied. Includes the action name, field name, condition GRNs for identifying the target resource, and the rate value. * Required if targetType is “action” priority int  0 ~ 2147483646 Priority of buff application Determines the order in which BuffEntryModels are evaluated. Entries with smaller values are evaluated first. When multiple buffs target the same field, the application order affects the final result due to the interaction between Rate Add and Mul operations. applyPeriodScheduleEventId string ~ 1024 chars Event period A unique resource name assigned to all information handled by GS2\" \u003e GRN to apply buff GRN of a GS2-Schedule event that controls when this buff is active. When specified, the buff is only applied during the event’s scheduled period. If not specified, the buff is always active. BuffTargetModel Buff Target Model Defines the target GS2 resource model and field for buff application. Specifies which model’s field value should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetModelName string (enum) enum { }  Model type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric field on the target model whose value will be modified by the buff. For example, a field representing experience points, attack power, or other numerical attributes. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Adjustment rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the field value after rate calculations. BuffTargetAction Buff Target Action Defines the target GS2 action and parameter for buff application. Specifies which action’s parameter should be modified by the buff, along with condition GRNs that identify the specific resource instance and the rate value to apply.  targetActionName string (enum) enum { \"Gs2Experience:AddExperienceByUserId\" , \"Gs2Experience:SubExperience\" , \"Gs2Experience:SubExperienceByUserId\" , \"Gs2Inventory:AcquireItemSetByUserId\" , \"Gs2Inventory:ConsumeItemSet\" , \"Gs2Inventory:ConsumeItemSetByUserId\" , \"Gs2Inventory:AcquireSimpleItemsByUserId\" , \"Gs2Inventory:ConsumeSimpleItems\" , \"Gs2Inventory:ConsumeSimpleItemsByUserId\" , \"Gs2Inventory:AcquireBigItemByUserId\" , \"Gs2Inventory:ConsumeBigItem\" , \"Gs2Inventory:ConsumeBigItemByUserId\" , \"Gs2Limit:CountUp\" , \"Gs2Limit:CountUpByUserId\" , \"Gs2Money:DepositByUserId\" , \"Gs2Money:Withdraw\" , \"Gs2Money:WithdrawByUserId\" , \"Gs2Money2:DepositByUserId\" , \"Gs2Money2:Withdraw\" , \"Gs2Money2:WithdrawByUserId\" , \"Gs2Stamina:ConsumeStamina\" , \"Gs2Stamina:ConsumeStaminaByUserId\" , \"Gs2Stamina:RecoverStaminaByUserId\" , }  Action type to apply buffs targetFieldName string  ~ 64 chars Field name to which the buff is applied The name of the numeric parameter on the target action whose value will be modified by the buff. For example, a parameter representing acquire count, consume amount, or reward quantity. conditionGrns List  1 ~ 10 items List of buff application condition GRNs GRN patterns that together identify the target resource instance for buff application. Multiple GRNs form a composite condition to precisely locate the resource. rate float  0 ~ 1000000 Rate The buff value to be applied. Its meaning depends on the expression type: for “Rate Add”, this value is added to the base rate; for “Mul”, it multiplies the current rate; for “Value Add”, it is directly added to the parameter value after rate calculations. BuffTargetGrn GRN pattern that identifies the resources used as conditions for applying buffs Specifies a GRN template with placeholders to identify which resource instance the buff should be applied to. The model name identifies the GS2 service model, and the GRN pattern contains context variables (e.g., region, ownerId, namespaceName) that are resolved at runtime to match the target resource.  targetModelName string  ~ 64 chars Buff application condition model name The name of the GS2 service model used to resolve the condition GRN. This identifies which service’s resource model the GRN pattern refers to. targetGrn string  ~ 1024 chars Buff application condition GRN A GRN template with context placeholders (e.g., {region}, {ownerId}) that is resolved at runtime to identify the specific resource instance targeted by the buff.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Buff Master Data Reference","url":"/api_reference/buff/master_data/"},{"content":"Master Data Format  version string  2020-04-30 Format version of master data categoryModels List ~ 1000 items Category Model Category Model defines the categories used to classify messages posted in chat rooms. Each category is identified by a numeric value, and you can configure whether posts using player access tokens are allowed or rejected per category. This enables use cases such as system-only announcement categories where only the server can post messages. Models CategoryModel Category Model Category Model defines the categories used to classify messages posted in chat rooms. Each category is identified by a numeric value, and you can configure whether posts using player access tokens are allowed or rejected per category. This enables use cases such as system-only announcement categories where only the server can post messages.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server category int  0 ~ 2147483645 Category A numeric identifier for the message category. Messages posted with this category number will follow the rules defined in this model, such as whether player posts are allowed or rejected. rejectAccessTokenPost string (enum) enum {   “Enabled”,   “Disabled” } Reject posts made using player access tokens When enabled, only server-side API calls (using user ID specification) can post messages in this category. This is useful for system announcements or server-generated messages that should not be posted by players directly. Definition Description “Enabled” Reject posts made using player access tokens “Disabled” Allow posts made using player access tokens","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Chat Master Data Reference","url":"/api_reference/chat/master_data/"},{"content":"Master Data Format  version string  2020-04-30 Format version of master data entryModels List ~ 10000 items Entry Model An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model. Models EntryModel Entry Model An Entry Model is master data that defines what can be recorded in the Dictionary within GS2-Dictionary. Each Entry Model represents a type of entity recorded in the Dictionary, such as monsters, items, or avatar parts. The possession state of an entry is managed as a binary state—recorded or not recorded—and there is no concept of quantity or stacking for a single Entry Model.  entryModelId string * ~ 1024 chars Entry Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Entry Model name 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.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Dictionary Master Data Reference","url":"/api_reference/dictionary/master_data/"},{"content":"Master Data Format  version string  2019-03-01 Format version of master data distributorModels List ~ 100 items Distributor Model A Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages. Models DistributorModel Distributor Model A Distributor Model is an entity that defines the policy applied when acquiring resources beyond the inventory capacity. By processing acquisitions through GS2-Distributor, overflow resources can be forwarded as GS2-Inbox messages.  distributorModelId string * ~ 1024 chars Distributor Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Distributor Model name Distributor 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. inboxNamespaceId string ~ 1024 chars GS2-Inbox namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN to transfer overflow resources When a resource acquisition exceeds the player’s inventory capacity, the overflow resources are forwarded as a message to the specified GS2-Inbox namespace. The player can then claim the resources from their inbox at a later time. whiteListTargetIds List [] 0 ~ 1000 items Whitelist of target resource GRN prefixes that can be processed through GS2-Distributor Specify the GRN prefix of the target resources that can be processed for acquisition using this Distributor Model.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Distributor Master Data Reference","url":"/api_reference/distributor/master_data/"},{"content":"Master Data Format  version string  2023-07-18 Format version of master data balanceParameterModels List ~ 10000 items Balance Parameter Model Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters. rarityParameterModels List ~ 10000 items Rarity Parameter Model Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions. Models BalanceParameterModel Balance Parameter Model Defines the drawing conditions for balance parameters. Balance parameters distribute a fixed total value across multiple parameter slots. For example, a weapon with a total power of 100 might have ATK=60, DEF=30, SPD=10. The initial value strategy determines how values are assigned: average distributes evenly, while lottery randomly allocates the total across parameters.  balanceParameterModelId string * ~ 1024 chars Balance Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Balance Parameter Model name Balance Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. totalValue long  0 ~ 9223372036854775805 Total value The fixed total that is distributed across all parameter slots. When parameters are drawn, the individual values will always sum to this total regardless of the allocation strategy used. initialValueStrategy string (enum) enum {   “average”,   “lottery” } “average” Initial value setting policy Determines how the total value is distributed across parameter slots when first assigned. average divides the total evenly among all parameters, while lottery randomly distributes the total to create varied parameter combinations. Definition Description “average” Average “lottery” Lottery parameters List  1 ~ 10 items Balance parameter value model list Defines the parameter slots available for this balance parameter. Each entry specifies a named parameter slot (e.g., ATK, DEF, SPD) with optional metadata. The total value is distributed across these slots. BalanceParameterValueModel Balance Parameter Value Model Defines a single parameter slot available within a balance parameter. Each entry specifies a named slot (e.g., ATK, DEF, SPD) that receives a portion of the total value during the drawing process.  name string  ~ 64 chars Name The identifier for this parameter slot (e.g., ATK, DEF, SPD). Must be unique within the balance parameter model. Used as the key when storing and retrieving drawn parameter values. metadata string ~ 512 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. RarityParameterModel Rarity Parameter Model Defines the drawing conditions for rarity parameters. Rarity parameters use a weighted lottery system to determine both the number of parameters granted and the specific values assigned. First, the number of parameter slots to fill is determined by a weighted draw from the parameter count model list. Then, each slot’s value is selected by a weighted draw from the parameter value model list, providing randomized equipment attributes with controlled probability distributions.  rarityParameterModelId string * ~ 1024 chars Rarity Parameter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rarity Parameter Model name Rarity Parameter Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. maximumParameterCount int  1 ~ 10 Maximum number of parameters to be given The upper limit on the number of parameter slots that can be granted to a resource. The actual number granted is determined by a weighted draw from the parameter count model list, but will never exceed this value. parameterCounts List  1 ~ 10 items Rarity parameter count model list Defines the weighted lottery entries for determining how many parameter slots are granted. Each entry specifies a count and a draw weight. Higher weights increase the probability of that count being selected. parameters List  1 ~ 1000 items Rarity parameter value model list Defines the pool of possible parameter values that can be drawn. Each entry specifies a parameter name, resource details, and a draw weight. When filling parameter slots, values are selected from this pool via weighted lottery without replacement. RarityParameterCountModel Rarity Parameter Count Model Defines a single entry in the weighted lottery for determining how many parameter slots are granted to a resource. Each entry pairs a parameter count with a draw weight, allowing fine-grained control over the probability distribution of parameter quantities.  count int  0 ~ 10 Count The number of parameter slots to grant when this entry is drawn. For example, a count of 3 means the resource will receive 3 parameter values selected from the value model pool. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when determining the parameter count. Higher values increase the probability of this count being selected. The actual probability is this weight divided by the sum of all weights in the count model list. RarityParameterValueModel Rarity Parameter Value Model Defines a single entry in the weighted lottery pool for rarity parameter values. Each entry specifies a parameter name, game-defined resource details, and a draw weight that determines its selection probability relative to other entries in the pool.  name string  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. metadata string ~ 512 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. resourceName string  ~ 64 chars Parameter Resource Name for Game (Not used for GS2) A game-defined resource type name associated with this parameter value (e.g., “fire_attack”, “ice_resist”). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. resourceValue long  0 ~ 9223372036854775805 Parameter Resource Value for Game (Not used for GS2) A game-defined numeric value for this parameter (e.g., 50 for +50 attack power). GS2 does not use this value for its own operations; it is passed through to the drawn result for use in game logic. weight int  1 ~ 2147483646 Draw Weight The relative weight used in the weighted lottery when selecting parameter values. Higher values increase the probability of this entry being selected. The actual probability is this weight divided by the sum of all weights in the pool.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Enchant Master Data Reference","url":"/api_reference/enchant/master_data/"},{"content":"Master Data Format  version string  2020-08-22 Format version of master data rateModels List ~ 10000 items Enhancement Rate Model The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity. unleashRateModels List ~ 10000 items Unleash Rate Model Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step. Models RateModel Enhancement Rate Model The enhancement rate is data that defines the materials used for enhancement and the target of enhancement. Both material data and enhancement target data must be managed in GS2-Inventory. The experience value obtained from the enhancement is recorded in GS2-Inventory metadata in JSON format. Here, it is necessary to describe at which level of the metadata the experience value is stored. A correction value can be applied to the amount of experience value that can be obtained with a certain probability of great success during enhancement. The probability of that draw is also defined in this entity.  rateModelId string * ~ 1024 chars Enhancement Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for enhancement targets Specifies the GS2-Inventory inventory model that holds the items eligible for enhancement. The item to be enhanced must belong to this inventory model. acquireExperienceSuffix string  ~ 1024 chars Suffix to be assigned to the property ID that stores the experience value obtained from GS2-Experience A string appended to the item’s property ID to form the GS2-Experience property ID where experience is stored. This allows the same item to have multiple experience types (e.g., “level” for character level, “like” for affinity). materialInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable as enhancement material Specifies the GS2-Inventory inventory model that holds the items usable as enhancement materials. The experience value each material provides is defined in the item model’s metadata using the JSON hierarchy specified by acquireExperienceHierarchy. acquireExperienceHierarchy List 0 ~ 10 items Hierarchical structure of JSON data defining acquisition experience values to be stored in ItemModel metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. For example, to define metadata with a structure like: { “aaa”: { “bbb”: { “experienceValue”: 100 } } } Specify it as: [ “aaa”, ‘bbb’, “experienceValue” ] Details are explained in the Microservices Introduction / GS2-Enhance section. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gained as a result of enhancement Specifies the GS2-Experience experience model where the experience points obtained from enhancement are recorded. The experience is added to the property identified by combining the target item’s property ID with the acquireExperienceSuffix. bonusRates List 0 ~ 1000 items Experience gain bonus Defines a weighted lottery for bonus experience multipliers during enhancement. Each entry specifies a multiplier (e.g., 1.5 for 150%) and a draw weight. When enhancement is performed, one entry is selected by weighted lottery to determine whether a “great success” bonus applies to the experience gained. BonusRate Experience Gain Bonus Defines a single entry in the weighted lottery for determining the experience bonus multiplier during enhancement. By configuring multiple entries with different rates and weights, you can implement “great success” or “super success” mechanics with controlled probabilities.  rate float 1.0 0 ~ 10000 Experience bonus multiplier (1.0 = no bonus) The multiplier applied to the base experience value when this entry is drawn. A value of 1.0 means normal enhancement with no bonus, 1.5 means 150% experience (great success), 2.0 means 200% experience (super success), and so on. weight int 1 0 ~ 2147483645 Lottery weight The relative weight used in the weighted lottery when selecting the bonus rate. Higher values increase the probability of this bonus rate being selected. The actual probability is this weight divided by the sum of all weights in the bonus rate list. UnleashRateModel Unleash Rate Model Defines the conditions for limit breaking (unleashing) items. Associates an item managed in GS2-Inventory with a GS2-Grade grade model to enable grade progression. Each grade level can require consuming a different number of duplicate items, allowing fine-grained control over the cost of each limit break step.  unleashRateModelId string * ~ 1024 chars Unleash Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Unleash Rate Model name Unleash Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). description string ~ 1024 chars Description 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. targetInventoryModelId string  ~ 1024 chars GS2-Inventory Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN usable for unleash targets Specifies the GS2-Inventory inventory model that holds the items eligible for limit breaking. The item to be unleashed and the duplicate items consumed as material must both belong to this inventory model. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN Specifies the GS2-Grade grade model that tracks the limit break level of the target item. When a limit break is successfully performed, the item’s grade is incremented in this grade model. gradeEntries List  1 ~ 1000 items List of Grade Entry Defines the material cost for each grade level of the limit break. Each entry maps a grade value to the number of duplicate items that must be consumed to reach that grade. For example, grade 1 might require 1 duplicate, grade 2 might require 3 duplicates, and so on. UnleashRateEntryModel Unleash Rate Entry Model Defines the material cost for a single grade level in a limit break progression. Each entry specifies which grade value it applies to and how many duplicate items of the same type must be consumed to achieve that grade.  gradeValue long  1 ~ 1000 Target grade The grade value that this entry defines the cost for. When performing a limit break to this grade level, the number of items specified by needCount will be consumed. needCount int  1 ~ 1000 How many items of the same type to consume The number of duplicate items that must be consumed to perform the limit break to the target grade. These items are of the same item model as the item being unleashed.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Enhance Master Data Reference","url":"/api_reference/enhance/master_data/"},{"content":"Master Data Format  version string  2019-08-19 Format version of master data rateModels List ~ 10000 items Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange. incrementalRateModels List ~ 10000 items Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis. Models RateModel Exchange Rate Model Exchange Rate Model is an entity that defines the rate used to exchange one resource for another. In addition to the rate at which a resource can be exchanged immediately, a rate can also be set at which a resource can be exchanged after a certain amount of time in real time has elapsed. Exchange rates that after a certain period of real time has elapsed can further define the resources required to perform an immediate exchange.  rateModelId string * ~ 1024 chars Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Exchange Rate Model name Exchange Rate 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. timingType string (enum) enum {   “immediate”,   “await” } “immediate” Type of exchange Determines when rewards are delivered after performing the exchange. immediate delivers rewards instantly upon exchange execution. await requires real-time to elapse before rewards can be claimed, creating a waiting period (e.g., crafting time). Definition Description “immediate” Immediate “await” Waiting for real time to pass lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action IncrementalRateModel Incremental Cost Exchange Rate Model Normal exchange rates always provide exchanges at a constant rate. With incremental exchange rates, you can define a rate that increases in cost as the number of exchanges increases. For example, the first exchange is performed at a rate of 1:1, but the second exchange is performed at a rate of 2:1. By defining such a rate, you can increase the value of the resources obtained by the player as the game progresses. The number of exchanges can be reset after a certain period of real time has elapsed. This is useful for resetting the number of exchanges on a daily or weekly basis.  incrementalRateModelId string * ~ 1024 chars Incremental Cost Exchange Rate Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. calculateType string (enum) enum {   “linear”,   “power”,   “gs2_script” }  Calculation method for cost increase amount Determines how the exchange cost escalates with each exchange. linear calculates cost as baseValue + (coefficientValue * exchangeCount). power calculates cost as coefficientValue * (exchangeCount + 1)^2. gs2_script delegates the calculation to a custom GS2-Script for arbitrary logic. Definition Description “linear” Base Value + (Coefficient * Number of Exchanges) “power” Coefficient * (Number of Exchanges + 1) ^ 2 “gs2_script” Custom logic implemented with GS2-Script baseValue long {calculateType} == “linear”  0 ~ 9223372036854775805 Base Value The initial cost for the first exchange when using the linear calculation type. The total cost is calculated as: baseValue + (coefficientValue * exchangeCount). * Required if calculateType is “linear” coefficientValue long {calculateType} in [“linear”, “power”]  0 ~ 9223372036854775805 Coefficient Value The multiplier that controls how quickly costs escalate with each exchange. In linear mode, each exchange adds this value to the cost. In power mode, the cost is calculated as: coefficientValue * (exchangeCount + 1)^2. * Required if calculateType is “linear”,“power” calculateScriptId string {calculateType} == “gs2_script”  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of cost calculation script Script Trigger Reference - calculateCost * Required if calculateType is “gs2_script” exchangeCountId string  ~ 1024 chars GS2-Limit Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for managing exchange execution counts References a GS2-Limit limit model that tracks how many times each user has performed this incremental exchange. The count is used to calculate the escalating cost and can be reset periodically (e.g., daily or weekly) using GS2-Limit’s reset timing. maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Exchange Master Data Reference","url":"/api_reference/exchange/master_data/"},{"content":"Master Data Format  version string  2019-01-11 Format version of master data experienceModels List ~ 100 items Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank. Models ExperienceModel Experience Model Defines the rules for an experience and rank system. Sets thresholds for the experience required to rank up, as well as the default rank cap and maximum rank cap. The rank cap limits the maximum rank a status can reach, and can be raised per-status up to the maximum rank cap (e.g., through limit breaking). Optionally includes acquire action rate tables that adjust reward multipliers based on the current rank.  experienceModelId string * ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Experience Model name Experience 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. defaultExperience long 0 0 ~ 9223372036854775805 Initial Experience Value The experience value assigned to a newly created status. Typically set to 0 so that players start at the beginning of the progression. The initial rank is determined from this value using the rank threshold table. defaultRankCap long  0 ~ 9223372036854775805 Initial value of rank cap The default maximum rank that a newly created status can reach. Experience beyond this rank’s threshold is discarded or triggers an overflow script. The rank cap can be raised per-status up to maxRankCap through operations like limit breaking. maxRankCap long  0 ~ 9223372036854775805 Maximum rank cap The absolute upper limit for the rank cap. Even through rank cap increase operations (such as limit breaking), the rank cap cannot exceed this value. Must be greater than or equal to defaultRankCap. rankThreshold Threshold  Rank Up Threshold References the threshold table that defines the cumulative experience values required for each rank. The number of entries in the threshold determines the maximum possible rank, and each entry’s value specifies the experience needed to reach the next rank. acquireActionRates List 0 ~ 100 items List of Reward addition tables Defines rank-based multiplier tables that adjust reward quantities when the status’s rank is used as a reference. Each table maps ranks to multipliers, enabling mechanics like higher-rank characters receiving more rewards from the same actions. Threshold Rank Up Threshold The Rank Up Threshold is a sequence of numbers needed to determine rank (level) from experience. If the value [10, 20] is set, experience values between 1 and 9 are rank 1, experience values between 10 and 19 are rank 2, experience values at 20 are rank 3, and no more experience values can be obtained.  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. values List  1 ~ 10000 items List of Rank Up Experience Threshold An ordered array of cumulative experience values defining the rank progression. The number of entries determines the maximum achievable rank. For example, [10, 20] means rank 1 at 0-9 EXP, rank 2 at 10-19 EXP, and rank 3 at 20+ EXP (with no further gains possible). AcquireActionRate Reward Addition Table Defines a rank-based multiplier table that adjusts reward quantities based on the status’s current rank. Each entry in the table corresponds to a rank and specifies a multiplier applied to the acquisition amount. Supports both standard double-precision values and big number string representations for large-scale calculations.  name string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. mode string (enum) enum {   “double”,   “big” } “double” Reward addition table type Selects the numeric precision for the multiplier values. Use “double” for standard floating-point numbers (up to 2^48), or “big” for string-represented numbers supporting up to 1024 digits when large-scale calculations are needed. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 10000 items Amount added per rank (multiplier) An array of multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 10000 items Amount added per rank (multiplier) An array of string-represented multiplier values indexed by rank. The i-th entry defines the reward multiplier applied when the status is at rank i. Used when the mode is set to “big” for calculations requiring large-number precision. * Required if mode is “big”","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Experience Master Data Reference","url":"/api_reference/experience/master_data/"},{"content":"Master Data Format  version string  2019-09-09 Format version of master data moldModels List ~ 100 items Form Storage Area Model If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually. propertyFormModels List ~ 100 items Property Form Model An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment. Models FormModel Form Model Form Model is an entity representing the configuration status. You can define slots as areas that can be formed. For weapons and armor, parts such as “right hand”, “left hand”, “body”, and “arm” can be used as slots, and for parties, positions such as “vanguard”, “midfield”, and “rear guard” can be expressed as slots.  formModelId string * ~ 1024 chars Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Model name Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions that make up this form. Each slot represents an assignable position, and the slot names must be unique within the form. For equipment, this might include slots like “weapon”, “armor”, “accessory”. For parties, slots like “position_1”, “position_2”, etc. SlotModel Slot Model Defines a single slot within a form model. A slot represents an assignable position where a game resource (such as an item, character, or equipment) can be placed. The property regex validates what values can be assigned to the slot.  name string  ~ 128 chars Slot Model name A unique identifier for this slot within the form model. For equipment forms, names like “right_hand” or “body” are typical. For party forms, names like “vanguard” or “rear_guard” are used. propertyRegex string “.*” ~ 512 chars Regular expressions for values that can be set as properties A regex pattern that validates the property ID values assignable to this slot. For example, restricting to specific GS2-Inventory item GRNs or GS2-Dictionary entry GRNs. Defaults to “.*” which allows any value. metadata string ~ 512 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. MoldModel Form Storage Area Model If it is a party composition, it is intended to be saved in the form of “fire attribute party” or “water attribute party”. The number of areas that can be saved can be limited or expanded individually.  moldModelId string * ~ 1024 chars Form Storage Area A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Form Storage Area Model name Form Storage Area 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. initialMaxCapacity int  1 ~ 2147483646 Initial capacity to store forms The default number of form save slots available to each player for this mold. For example, if set to 3, the player can initially save up to 3 different formations (e.g., “fire party”, “water party”, “wind party”). Can be expanded per-player up to maxCapacity. maxCapacity int  1 ~ 2147483646 Maximum capacity to store forms The absolute upper limit for the number of form save slots per player for this mold. Even through capacity expansion operations, the capacity cannot exceed this value. Must be greater than or equal to initialMaxCapacity. formModel FormModel  Form Model PropertyFormModel Property Form Model An entity that represents the composition status. The difference between Mold / Form is that Mold / Form defines the number of slots and records the composition in each slot, and Property Form is used to represent compositions that are difficult to determine the number of slots in advance, such as setting skills for owned equipment.  propertyFormModelId string * ~ 1024 chars Property Form Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Property Form Model name Property Form 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. slots List  1 ~ 10 items List of Slot Model The ordered list of slot definitions for this property form. Unlike Mold/Form where the number of forms is limited by capacity, property forms are identified by a property ID and can exist for any owned resource. Slot names must be unique within the form.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Formation Master Data Reference","url":"/api_reference/formation/master_data/"},{"content":"Master Data Format  version string  2023-12-25 Format version of master data gradeModels List ~ 100 items Grade Model A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade. Models GradeModel Grade Model A Grade Model is an entity that indicates the rank of characters and equipment, and allows you to set the rank cap for GS2-Experience based on the grade.  gradeModelId string * ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Grade Model name Grade 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. defaultGrades List 0 ~ 100 items List of Default Grade Models An ordered list of default grade rules evaluated when creating a new status. Each entry defines a property ID regex pattern and the grade value to assign when matched. If no pattern matches, the default grade value of 0 is used. experienceModelId string  ~ 1024 chars GS2-Experience Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Experience experience model to link with this grade model. When a grade value changes, the corresponding rank cap in the linked experience model is automatically updated based on the grade entry mappings. This enables grade-driven progression where higher grades unlock higher rank caps. gradeEntries List  1 ~ 100 items List of Grade Entry Models The ordered list of grade entries that map each grade value to a rank cap for the linked GS2-Experience model. The index in the array corresponds to the grade value, so the first entry (index 0) defines the rank cap for grade 0, the second for grade 1, and so on. acquireActionRates List 0 ~ 100 items List of Reward Addition Tables A collection of named multiplier tables used to scale reward amounts based on grade. Multiple tables can be defined to apply different scaling rules to different types of rewards (e.g., experience points, currency, items). DefaultGradeModel Default Grade Model You can set the default grade value according to the match of the property ID regular expression when creating a new grade.  propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern matched against the property ID of a newly created grade status. When the property ID matches this pattern, the specified default grade value is assigned as the initial grade instead of 0. Patterns are evaluated in order, and the first match is used. defaultGradeValue long  0 ~ 9223372036854775805 Default Grade Value The initial grade value assigned to a newly created status when its property ID matches the propertyIdRegex pattern. This value determines the starting rank cap for the linked GS2-Experience model, as the grade entry at this index defines the corresponding rank cap. GradeEntryModel Grade Entry Model Defines the mapping between a grade value and a rank cap for the linked GS2-Experience model. Each entry also specifies regex patterns for matching property IDs, enabling the system to determine which resources can be used for grade-up operations and how their property IDs are transformed.  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. rankCapValue long  0 ~ 9223372036854775805 Rank Cap Value The rank cap value to set in the linked GS2-Experience model when this grade is applied. When a player’s grade changes to the value corresponding to this entry, the rank cap of the associated experience status is automatically updated to this value, controlling the maximum achievable rank. propertyIdRegex string  ~ 1024 chars Property ID Regex A regular expression pattern applied to the grade status’s property ID to extract variables for grade-up matching. Capture groups (parenthesized parts) in this pattern become available as $1, $2, etc. in gradeUpPropertyIdRegex. For example, a pattern like “character-(.+)” extracts the character identifier for use in matching grade-up material property IDs. gradeUpPropertyIdRegex string  ~ 1024 chars Grade-Up Property ID Regex A regular expression pattern that identifies which resource property IDs can be consumed for grade advancement. This pattern can reference capture groups from propertyIdRegex using $1, $2, etc. For example, if propertyIdRegex extracts “sword-001” as $1, this pattern might be “grade-up-material-$1” to match materials specific to that sword. AcquireActionRate Reward Addition Table Defines a named multiplier table that scales reward amounts based on the current grade value. Each grade value maps to a multiplier applied to acquire actions in transactions, allowing higher-graded characters or equipment to receive proportionally more rewards. Supports both standard double-precision mode and big number mode for extremely large values.  name string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. mode string (enum) enum {   “double”,   “big” } “double” Reward Addition Table Type Selects the numeric precision mode for multiplier values. “double” mode uses standard floating-point numbers suitable for most cases. “big” mode uses string-represented numbers supporting up to 1024 digits, for games requiring extremely large value calculations. Definition Description “double” Floating point number less than 2^48 “big” Floating point number less than 1024 digits rates List {mode} == “double”  1 ~ 1000 items Multiplier List per Grade (double mode) An array of reward multipliers indexed by grade value, using double-precision floating-point numbers. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “double”. * Required if mode is “double” bigRates List {mode} == “big”  1 ~ 1000 items Multiplier List per Grade (big mode) An array of reward multipliers indexed by grade value, using string-represented numbers for extended precision. The entry at index 0 is the multiplier for grade 0, index 1 for grade 1, and so on. Used when mode is set to “big” for games requiring very large number calculations. * Required if mode is “big”","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Grade Master Data Reference","url":"/api_reference/grade/master_data/"},{"content":"Master Data Format  version string  2024-04-25 Format version of master data guildModels List ~ 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.  guildModelId string * ~ 1024 chars Guild Model A unique resource name assigned to all information handled by GS2\" \u003e 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  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.  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.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Guild Master Data Reference","url":"/api_reference/guild/master_data/"},{"content":"Master Data Format  version string  2023-06-06 Format version of master data categoryModels List ~ 100 items Category Model A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time. Models CategoryModel Category Model A Category Model is an entity that defines a waiting category in which idle rewards can be earned over time. The settings include information such as the reward for each waiting time and the maximum idle time.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category 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. rewardIntervalMinutes int  0 ~ 2147483646 Reward Interval (Minutes) The time interval in minutes between each idle reward. For example, if set to 60, the user earns one reward unit for every 60 minutes of idle time. The total number of rewards is calculated as (elapsed idle minutes) / rewardIntervalMinutes, cycling through the acquireActions array. defaultMaximumIdleMinutes int  0 ~ 2147483646 Default Maximum Idle Time (Minutes) The default maximum idle time in minutes for new statuses in this category. Idle time beyond this limit does not accumulate additional rewards. This value is copied to each status’s maximumIdleMinutes when the status is created, and can be extended per-user via transactions. rewardResetMode string (enum) enum {   “Reset”,   “CarryOver” } “Reset” Reward Reset Mode Determines how idle time is handled after the user receives rewards. “Reset” sets the idle time back to zero, meaning any partial interval time is lost. “CarryOver” preserves the remaining time that was not enough to earn an additional reward, so it counts toward the next reward cycle. Definition Description “Reset” Reset waiting time to 0 “CarryOver” Carry over the remaining time that was insufficient to receive a reward acquireActions List [] 1 ~ 100 items List of acquire actions for each waiting time Assuming that the waiting time is “X minutes”, “X / rewardIntervalMinutes” will be the number of rewards that can be received, but by looping the elements specified in this array, different rewards can be given for each waiting time. idlePeriodScheduleId string ~ 1024 chars Idle Period Schedule ID The GRN of a GS2-Schedule event that defines the time period during which idle time accumulates. When set, idle time only counts while the event is active. If the event repeats, the status tracks the repetition count and resets idle time when a new cycle begins, ensuring rewards are calculated per event period. receivePeriodScheduleId string ~ 1024 chars Receive Period Schedule ID The GRN of a GS2-Schedule event that defines the time window during which users can claim accumulated idle rewards. When set, reward claims are only accepted while the event is active. This allows time-limited reward collection periods separate from the idle accumulation period. AcquireActionList Acquire Action List A wrapper that groups multiple acquire actions to be granted together for a single reward interval. Each AcquireActionList corresponds to one reward cycle in the category model’s acquireActions array, enabling different reward combinations at each interval.  acquireActions List [] 0 ~ 100 items List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. AcquireAction Acquire Action Represents a single acquire action used as an idle reward. Consists of an action type (e.g., add items, increase currency) and its request parameters. When idle rewards are claimed, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Idle Master Data Reference","url":"/api_reference/idle/master_data/"},{"content":"Master Data Format  version string  2020-03-12 Format version of master data globalMessages List ~ 1000 items Global Message Global Message is a mechanism for delivering messages to all game players. Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message. Unreceived Global Messages within the validity period are copied to the player’s message box. Models GlobalMessage Global Message Global Message is a mechanism for delivering messages to all game players. Global messages can have an expiration time, and each game player can receive a Global Message by executing the process of receiving a Global Message. Unreceived Global Messages within the validity period are copied to the player’s message box.  globalMessageId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Global Message for all users * Set automatically by the server name string  ~ 128 chars Global Message name Global Message-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string  ~ 4096 chars Metadata Arbitrary data representing the global message content, such as a JSON string containing the message title, body text, and display parameters. When a user receives this global message, the metadata is copied to the individual message in their inbox. GS2 does not interpret this value. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions to be executed when a user opens the message copied from this global message. These actions are copied along with the metadata to each user’s individual message. Up to 100 actions per global message. expiresTimeSpan TimeSpan Expiration Time Span The duration from the time a user receives (copies) this global message until the copied message expires and is automatically deleted from their inbox. Specified as a combination of days, hours, and minutes. Messages are deleted regardless of read status when the expiration is reached, including any unclaimed attached rewards. messageReceptionPeriodEventId string ~ 1024 chars Message Reception Period Event ID The GRN of a GS2-Schedule event that defines the time window during which this global message can be received (copied to users’ inboxes). Outside this period, the global message is not delivered even if a user triggers the receive global messages operation. Useful for time-limited event announcements or seasonal campaign rewards. TimeSpan Time Span Represents a duration of time as a combination of days, hours, and minutes. Used to define the expiration period for messages relative to their reception time. For example, a TimeSpan of 7 days, 0 hours, 0 minutes means the message expires exactly one week after the user receives it.  days int 0 0 ~ 365 Days The number of days in this time span. Combined with hours and minutes to calculate the total duration. Maximum 365 days. hours int 0 0 ~ 24 Hours The number of hours in this time span. Combined with days and minutes to calculate the total duration. Maximum 24 hours. minutes int 0 0 ~ 60 Minutes The number of minutes in this time span. Combined with days and hours to calculate the total duration. Maximum 60 minutes. AcquireAction Acquire Action Represents a single acquire action attached to a message as a reward. Consists of an action type (e.g., add items to inventory, increase currency) and its request parameters. When a message is opened, these actions are assembled into transactions and executed to deliver the rewards to the user.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Inbox Master Data Reference","url":"/api_reference/inbox/master_data/"},{"content":"Master Data Format  version string  2019-02-05 Format version of master data inventoryModels List ~ 50 items Inventory Model Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity. simpleInventoryModels List ~ 50 items Simple Inventory Model In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation. bigInventoryModels List ~ 50 items Big Inventory Model In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits. Models InventoryModel Inventory Model Inventory is like a bag that stores items owned by game players. Inventory can have a set capacity and cannot be owned beyond its capacity.  inventoryModelId string * ~ 1024 chars Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Inventory Model name Inventory 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. initialCapacity int  0 ~ 2147483646 Initial Capacity The number of inventory slots available to a user when the inventory is first created. Each slot can hold one item stack. Users can expand their capacity up to maxCapacity through gameplay actions. maxCapacity int  0 ~ 2147483646 Maximum Capacity The upper limit of inventory slots that a user can expand to. Capacity cannot be increased beyond this value. When all slots are occupied and items cannot be stacked further, acquisition attempts will fail unless the overflow script handles the excess. protectReferencedItem bool? false Protect Referenced Items When enabled, item sets that have references registered (via the referenceOf mechanism) cannot be consumed or deleted. This prevents items that are in use by other systems (e.g., equipped gear, items bound to formations) from being accidentally removed. itemModels List [] 1 ~ 1000 items List of Item Models The item types that can be stored in this inventory. Each item model defines the stacking and acquisition behavior for one type of item. Up to 1000 item models per inventory model. ItemModel Item Model Items can be held in groups within a single inventory slot, such as Potion ×99. This grouping of multiple items into one slot is called “stacking,” and a maximum stack size can be set for each item. The behavior when the stack limit is reached can also be set for each item. Specifically, you can choose one of the following: Add a new inventory slot to allow further acquisition Prevent further acquisition once the limit is reached  itemModelId string * ~ 1024 chars Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Item Model name Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 2048 chars Metadata GS2-Enhance features a mechanism that works in conjunction with GS2-Inventory to perform enhancements. It sets the experience value when used as enhancement material in JSON format within the ItemModel metadata. Details are explained in the Microservices Introduction / GS2-Enhance section. stackingLimit long  1 ~ 9223372036854775805 Maximum Stackable Quantity The maximum number of this item that can be held in a single inventory slot (stack). When this limit is reached, the behavior depends on the allowMultipleStacks setting: either a new slot is allocated or further acquisition is blocked. allowMultipleStacks bool  Allow Multiple Stacks When enabled, if the stacking limit is reached, a new inventory slot is automatically allocated to store additional quantities of this item (consuming additional capacity). When disabled, acquisition is blocked once the stacking limit is reached in the existing slot. sortValue int  0 ~ 2147483646 Display Order A numeric value used to sort items within the inventory for display purposes. Lower values are displayed first. This value is also copied to ItemSet records to enable consistent ordering of possessed items. SimpleInventoryModel Simple Inventory Model In a normal InventoryModel, you could limit the amount of items that could be stored in your inventory. Simple Inventory, however, has no such functionality and simply stores the number of items in the inventory. However, the Simple Inventory provides APIs that allow increasing or decreasing multiple items in a single operation.  inventoryModelId string * ~ 1024 chars Simple Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Inventory Model name Simple Inventory 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. simpleItemModels List [] 1 ~ 1000 items List of Simple Item Models The item types that can be stored in this simple inventory. Unlike standard inventory, simple items have no stacking limits or capacity constraints. Up to 1000 item models per simple inventory model. SimpleItemModel Simple Item Model ItemModel allowed setting a maximum stackable quantity, enabling implementation where items exceeding a certain number could be split into multiple stacks. SimpleItem does not have such a function and simply stores the number of items in the possession of the item.  itemModelId string * ~ 1024 chars Simple Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Simple Item Model name Simple Item 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. BigInventoryModel Big Inventory Model In the normal InventoryModel and SimpleInventoryModel, the number of items that can be stored in the inventory is limited to the range of int64. In inflationary games, you may need a wider range of values. In the Big Inventory Model, the number of items that can be stored in the inventory can have an integer value of 1024 digits.  inventoryModelId string * ~ 1024 chars Big Inventory Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Inventory Model name Big Inventory 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. bigItemModels List [] 1 ~ 1000 items List of Big Item Models The item types that can be stored in this big inventory. Each big item model can hold quantities represented as integer strings up to 1024 digits. Up to 1000 item models per big inventory model. BigItemModel Big Item Model The Big Item Model defines items stored in a Big Inventory Model. Big Items can hold quantities that exceed the range of int64.  itemModelId string * ~ 1024 chars Big Item Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Big Item Model name Big Item 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.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Inventory Master Data Reference","url":"/api_reference/inventory/master_data/"},{"content":"Master Data Format  version string  2019-04-05 Format version of master data limitModels List ~ 100 items Usage Limit Model Usage Limit Model allows you to set the timing for resetting the usage count. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. Additionally, the maximum value for usage Limits is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha: - Items purchasable when the purchase counter is under 3 - When the above items are unavailable, another item purchasable if the purchase counter is under 5 The design assumes the ability to switch the “maximum count” based on the situation. Models LimitModel Usage Limit Model Usage Limit Model allows you to set the timing for resetting the usage count. The reset interval can be selected from five options: “Daily”, “Weekly”, “Monthly”, “Every fixed number of days” or “Not Reset”. Additionally, the maximum value for usage Limits is not fixed in the master data. This design allows the maximum allowed count to be changed dynamically depending on the game context. For example, in a step-up gacha: Items purchasable when the purchase counter is under 3 When the above items are unavailable, another item purchasable if the purchase counter is under 5 The design assumes the ability to switch the “maximum count” based on the situation.  limitModelId string * ~ 1024 chars Usage Limit Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Usage Limit Model name Usage Limit 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. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” }  Reset Timing Determines when the counter values under this limit model are automatically reset to zero. Choose from: notReset (permanent, never resets), daily (resets at the specified hour each day), weekly (resets on the specified day of the week), monthly (resets on the specified day of the month), or days (resets every fixed number of days from an anchor timestamp). All times are in UTC. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Reset Day of Month The day of the month on which counters are reset when resetType is “monthly”. Valid values are 1-31. If the specified day exceeds the number of days in the current month (e.g., 31 for February), the counter resets on the last day of that month. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Reset Day of Week The day of the week on which counters are reset when resetType is “weekly”. The reset occurs at the hour specified by resetHour (UTC) on this day. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Reset Hour The hour (0-23) in UTC at which counters are reset for daily, weekly, or monthly reset types. For example, a value of 0 means counters reset at midnight UTC. * Required if resetType is “monthly”,“weekly”,“daily” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of Days to Reset The interval in days between counter resets when resetType is “days”. The reset cycle is calculated from the anchorTimestamp. For example, if days is 7 and anchorTimestamp is Monday at noon, counters reset every Monday at noon. * Required if resetType is “days”","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Limit Master Data Reference","url":"/api_reference/limit/master_data/"},{"content":"Master Data Format  version string  2023-07-11 Format version of master data bonusModels List ~ 100 items Login Bonus Model Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days. Models BonusModel Login Bonus Model Login Bonus Model defines the distribution schedule for login bonuses. There are two schedule types: 《Schedule Mode》 and 《Streaming Mode》. In Schedule Mode, a GS2-Schedule event must be specified, and bonuses are distributed based on the number of days elapsed since the event’s start date. If the user misses a day partway through, the bonus for that day will not be granted. In Streaming Mode, the rewards configured for the bonus are distributed sequentially from the beginning each day. Streaming Mode also supports repetition; when enabled, the distribution restarts from the first reward after reaching the end of the stream. Both Schedule Mode and Streaming Mode provide a missed-bonus recovery feature. By paying a certain cost, users can receive bonuses they previously missed. However, if a GS2-Schedule event is associated, users cannot receive bonuses beyond the number of days elapsed since the event’s start date. Additionally, the recovery feature cannot be used when using Streaming Mode with repetition enabled. In both Schedule Mode and Streaming Mode, the maximum number of days that can be configured for bonuses is 100 days.  bonusModelId string * ~ 1024 chars Login Bonus Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Login Bonus Model name Login Bonus 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. mode string (enum) enum {   “schedule”,   “streaming” }  Mode Specifies the distribution schedule type for the login bonus. In “schedule” mode, rewards are tied to elapsed days since a GS2-Schedule event start date. In “streaming” mode, rewards are distributed sequentially from the beginning each day regardless of calendar date. Definition Description “schedule” Schedule Mode “streaming” Streaming Mode periodEventId string ~ 1024 chars Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule Event GRN that represents the period during which to enable login bonuses. In Schedule Mode, this field is required and determines the start date from which elapsed days are counted for reward distribution. In Streaming Mode, this field is optional; when specified, users cannot receive bonuses beyond the elapsed days since the event start. resetHour int {periodEventId} == \"\"  0 ~ 23 Reset Hour (UTC) The hour of day (0-23, UTC) at which the daily receive flag resets. This determines when a new day begins for login bonus purposes. Only required when periodEventId is not specified; when an event is set, the reset timing follows the event’s schedule. * Required if periodEventId is “\" repeat string (enum) enum {   “enabled”,   “disabled” } {mode} == “streaming”  Repeat Whether to restart distribution from the beginning after all rewards have been distributed. Only applicable in Streaming Mode. When enabled, the reward list loops back to the first entry after the last one is distributed. Note: the missed-bonus recovery feature cannot be used when repeat is enabled. Definition Description “enabled” Enabled “disabled” Disabled * Required if mode is “streaming” rewards List 0 ~ 100 items Rewards The ordered list of daily rewards. Each entry corresponds to one day’s login bonus, distributed sequentially from index 0. In Schedule Mode, the index maps to the number of elapsed days since the event start date. In Streaming Mode, the index maps to the number of login days. Up to 100 entries can be configured. missedReceiveRelief string (enum) enum {   “enabled”,   “disabled” } “disabled” Missed Receive Relief Whether to enable the missed-bonus recovery feature. When enabled, users can retroactively receive bonuses they missed by paying a specified cost (consume actions). Optionally, verify actions can be configured to check conditions before allowing recovery. This feature cannot be used when Streaming Mode with repeat enabled is active. Defaults to “disabled”. Definition Description “enabled” Enabled “disabled” Disabled missedReceiveReliefVerifyActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Verify Actions List of verify actions to execute before allowing missed-bonus recovery. These actions check preconditions (e.g., user eligibility) before the recovery is processed. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Reward Reward Represents a single day’s reward configuration for a login bonus. Each Reward contains a list of acquire actions that define what the user receives (e.g., items, currency, experience). The rewards array in BonusModel holds one Reward per day, distributed in order. Reward values can be modified at runtime through the buff system (BonusModelBuff) to apply rate multipliers to acquire actions.  acquireActions List  1 ~ 10 items List of Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies an acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. ConsumeAction Consume Action Defines an action for consuming resources from a user via the transaction mechanism. Used in missed-bonus recovery to specify the cost users must pay (e.g., deducting currency, consuming items). The action field specifies the type of consume action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action Defines an action for verifying conditions before proceeding with an operation. Used in missed-bonus recovery to check preconditions (e.g., user eligibility, resource availability) before allowing the recovery. The action field specifies the type of verify action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action Defines an action for granting resources to a user via the transaction mechanism. Used within rewards to specify what the user receives (e.g., adding items to inventory, granting currency, awarding experience points). The action field specifies the type of acquire action, and the request field contains the corresponding request parameters.  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-LoginReward Master Data Reference","url":"/api_reference/login_reward/master_data/"},{"content":"Master Data Format  version string  2019-02-21 Format version of master data lotteryModels List ~ 100 items Lottery Model Lottery Model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha. prizeTables List ~ 100 items Prize Table A prize can either specify an acquire action directly or reference another Prize Table. By nesting Prize Tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game. Models PrizeTable Prize Table A prize can either specify an acquire action directly or reference another Prize Table. By nesting Prize Tables, you can configure a two-step drawing process—for example, the first step determines the rarity such as SSR, SR, or R, and the second step selects a specific item corresponding to that rarity. This structure makes it easier to manage and adjust the overall distribution rates for each rarity in the game.  prizeTableId string * ~ 1024 chars Prize Table A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Prize Table name Prize Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. prizes List  1 ~ 100 items Prizes The list of prizes in this Prize Table. Each prize defines its draw weight (probability), the actions to execute when drawn, and optionally a draw limit. The actual draw probability of each prize is calculated as its weight divided by the total weight of all prizes in the table. Prize Prize A single prize entry within a Prize Table. A prize can either directly specify acquire actions (granting items, currency, etc.) or reference another Prize Table to perform a nested draw. Each prize has a draw weight that determines its relative probability of being drawn.  prizeId string  UUID ~ 36 chars Prize ID A unique identifier for this prize within the Prize Table. Used to track draw limits and as a reference when specifying failover prizes. type string (enum) enum {   “action”,   “prize_table” }  Prize Type Determines whether this prize directly grants rewards or delegates to another Prize Table. “action” specifies acquire actions to execute when drawn. “prize_table” references another Prize Table for a nested drawing (e.g., first draw determines rarity, second draw determines specific item). Definition Description “action” Acquire Actions for the prize “prize_table” Delegates the draw to another Prize Table (performs a nested draw). acquireActions List {type} == “action” [] 1 ~ 100 items List of Acquire Actions The list of acquire actions to execute when this prize is drawn. Multiple actions can be specified to grant several rewards at once (e.g., an item and currency together). * Enabled only if type is “action” drawnLimit int {type} == “action” 1 ~ 1000000 Maximum Number of Draws The maximum number of times this prize can be drawn across all users. When the limit is reached, the failover prize (limitFailOverPrizeId) is drawn instead. Used to implement limited-quantity prizes such as jackpot items. * Enabled only if type is “action” limitFailOverPrizeId string {type} == “action” and {drawnLimit} \u003e 0  ~ 32 chars Limit Failover Prize ID The ID of the prize to draw instead when this prize’s draw limit (drawnLimit) has been reached. Must reference another prize within the same Prize Table. * Required if type is “action” and drawnLimit is greater than 0 prizeTableName string {type} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to delegate the draw to. Used when the prize type is “prize_table” for nested drawing. * Required if type is “prize_table” weight int  1 ~ 2147483646 Draw Weight The relative weight of this prize in the Prize Table. The actual draw probability is calculated as this prize’s weight divided by the total weight of all prizes in the table. For example, if three prizes have weights of 70, 20, and 10, their draw probabilities are 70%, 20%, and 10% respectively. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action LotteryModel Lottery Model Lottery Model is an entity that defines the draw method and how to reference the draw table. Two draw methods are available: Normal Draw, which performs draws with a fixed probability each time, and Box Draw, where a predetermined number of prizes are placed in a box, and prizes are drawn from the box one by one with each draw. The lottery process uses a Prize Table. GS2-Script can be used to dynamically select the Prize Table with a different table when multiple drawings are performed. By using this mechanism, it is possible to apply a different Prize Table only once in a 10-round gacha.  lotteryModelId string * ~ 1024 chars Lottery Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). 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. mode string (enum) enum {   “normal”,   “box” }  Drawing Mode Select the prize drawing method. “normal” performs draws with a fixed probability each time (prizes can be drawn repeatedly). “box” places a predetermined number of prizes in a virtual box, and each draw removes a prize from the box (guaranteeing all prizes will eventually be drawn). Definition Description “normal” Normal Draw “box” Box Draw method string (enum) enum {   “prize_table”,   “script” }  Prize Table Selection Method Determines how the Prize Table is referenced. “prize_table” uses a statically specified Prize Table. “script” uses GS2-Script to dynamically select the Prize Table at draw time, enabling scenarios like applying a different Prize Table for one draw in a 10-draw gacha. Definition Description “prize_table” Static Prize Table “script” Dynamically selected Prize Table using GS2-Script prizeTableName string {method} == “prize_table”  ~ 128 chars Prize Table Name The name of the Prize Table to use for this lottery model. Required when the lottery method is “prize_table”. * Required if method is “prize_table” choicePrizeTableScriptId string {method} == “script”  ~ 1024 chars GS2-Script script A unique resource name assigned to all information handled by GS2\" \u003e GRN to determine the Prize Table Script Trigger Reference - choicePrizeTable * Required if method is “script”","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Lottery Master Data Reference","url":"/api_reference/lottery/master_data/"},{"content":"Master Data Format  version string  2020-06-24 Format version of master data ratingModels List ~ 50 items Rating Model GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value. seasonModels List ~ 50 items Season Model Defines the season-specific settings for Season Matchmaking, including the period of persistent gatherings, maximum participant count, and tier integration settings. Managed by GS2-Schedule for period control, and can be linked with GS2-Experience for persistent gathering within the same tier as needed. Models RatingModel Rating Model GS2 uses Glicko-2 as its rating algorithm. Glicko-2 has several parameters, but GS2-Matchmaking aggregates them into a single parameter, volatility, which represents the totality of the parameters. Volatility is a parameter that expresses the magnitude of change; the larger the value, the greater the change in the rating value.  ratingModelId string * ~ 1024 chars Rating Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Rating Model name Rating Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. initialValue int 1500 100 ~ 10000 Initial Rating Value The starting rate value assigned to new players when they first participate in rated matchmaking. Defaults to 1500. All players begin at the same rating and it adjusts based on match results. volatility int 100 1 ~ 20000 Rating Volatility A Glicko-2 parameter that controls how much the rating value changes after each match. Higher values cause larger rating fluctuations, making ratings adjust more quickly. Lower values result in more stable ratings that change gradually. Defaults to 100. SeasonModel Season Model Defines the season-specific settings for Season Matchmaking, including the period of persistent gatherings, maximum participant count, and tier integration settings. Managed by GS2-Schedule for period control, and can be linked with GS2-Experience for persistent gathering within the same tier as needed.  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. maximumParticipants int  2 ~ 1000 Maximum Number of Participants The maximum number of players that can join a single Season Gathering. Once this limit is reached, the Season Gathering is considered full and no more players can join. Must be between 2 and 1000. experienceModelId string ~ 1024 chars Experience Model A unique resource name assigned to all information handled by GS2\" \u003e GRN for Tier Management The GRN of the GS2-Experience experience model used to determine player tiers. The player’s rank within this experience model is used as their tier for matchmaking, ensuring players are grouped with others at a similar level. If not specified, tier-based grouping is disabled and all players are matched together regardless of level. challengePeriodEventId string  ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN The GRN of the GS2-Schedule event that defines the active period for this season. Season Gatherings can only be created and joined while this event is active. When the event period ends, the season closes and new matchmaking is no longer possible.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Matchmaking Master Data Reference","url":"/api_reference/matchmaking/master_data/"},{"content":"Master Data Format  version string  2022-08-28 Format version of master data areaModels List ~ 50 items Area divides space, and different areas can be treated as different spaces even if they have the same coordinates. Models AreaModel Area divides space, and different areas can be treated as different spaces even if they have the same coordinates.  areaModelId string * ~ 1024 chars Area Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Area Model name 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. layerModels List [] 0 ~ 1000 items List of layer models LayerModel Layers allow for multiple logical hierarchies within a single space. For example, it solves the problem of an Enemy being invisible in a space with a large number of characters. Characters are placed on Layer 1. If Enemies are placed on Layer 2, there is no need to worry about them becoming invisible, since each layer can specify the quantity to be acquired within a specified distance.  layerModelId string * ~ 1024 chars Layer Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Layer Model name 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.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-MegaField Master Data Reference","url":"/api_reference/mega_field/master_data/"},{"content":"Master Data Format  version string  2019-05-28 Format version of master data groups List ~ 20 items Mission Group Model A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission. counters List ~ 1000 items Counter Model Counter Model is an entity that can be set as a condition for accomplishing mission tasks. Since counter values can be referenced by multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions. Models CounterModel Counter Model Counter Model is an entity that can be set as a condition for accomplishing mission tasks. Since counter values can be referenced by multiple mission groups, a single counter can be set as an accomplishment condition for multiple mission groups, such as weekly and daily missions.  counterId string * ~ 1024 chars Counter Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. scopes List [] 1 ~ 20 items List of Counter reset timing Defines the scopes (reset timings or verify action conditions) for this counter. A single counter can have multiple scopes, allowing one counter to track values across different periods (e.g., daily, weekly, and cumulative totals simultaneously). challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that sets the period during which the counter can be operated Specifies the GS2-Schedule event that defines the time window during which this counter can be incremented or decremented. If not set, the counter can be operated at any time. CounterScopeModel Counter Reset Timing Model Defines a scope for a counter, which determines how and when the counter value is reset. A scope can be either a reset timing (daily, weekly, monthly, fixed-day interval, or never) or a verify action condition. Each counter can have multiple scopes to track values across different periods.  scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Determines how the counter scope is defined. “resetTiming” uses a periodic reset schedule, while “verifyAction” uses a verify action to determine whether the counter value applies. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the counter value for this scope is reset. Choose from: not reset (permanent cumulative), daily, weekly, monthly, or every fixed number of days. Only used when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the counter value resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the counter value resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the counter value resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name A unique name that identifies this verify action condition scope. Used to look up the corresponding scoped value in the counter. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” condition VerifyAction {scopeType} == “verifyAction”  Condition The verify action that determines whether the counter value for this scope is applicable. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between counter value resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action MissionGroupModel Mission Group Model A mission group is an entity that groups tasks by counter reset timing. For example, one group for daily missions. One group for Weekly Mission.  missionGroupId string * ~ 1024 chars Mission Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Group Model name Mission Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. tasks List [] 0 ~ 1000 items List of Mission Task The mission tasks belonging to this group. Each task defines a completion condition (counter threshold or verify actions) and the rewards granted upon accomplishment. resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } “notReset” Reset timing Determines when the mission group’s completion status is reset. Choose from: not reset (permanent), daily, weekly, monthly, or every fixed number of days from an anchor timestamp. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days resetDayOfMonth int {resetType} == “monthly”  1 ~ 31 Date to reset The day of the month on which the mission group resets. If the specified value exceeds the number of days in the month, it is treated as the last day of that month. Only used when resetType is “monthly”. * Required if resetType is “monthly” resetDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {resetType} == “weekly”  Day of the week to reset The day of the week on which the mission group resets. Only used when resetType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if resetType is “weekly” resetHour int {resetType} in [“monthly”, “weekly”, “daily”]  0 ~ 23 Hour of Reset The hour (0-23) at which the mission group resets. Used in combination with daily, weekly, or monthly reset types. * Required if resetType is “monthly”,“weekly”,“daily” completeNotificationNamespaceId string ~ 1024 chars Push notifications when mission tasks are accomplished The GS2-Gateway namespace GRN used to deliver push notifications when a mission task in this group is accomplished. Allows the game client to be notified in real-time. anchorTimestamp long {resetType} == “days”  Base date and time for counting elapsed days Unix time, milliseconds * Required if resetType is “days” days int {resetType} == “days”  1 ~ 2147483646 Number of days to reset The interval in days between resets, counting from the anchor timestamp. Only used when resetType is “days”. * Required if resetType is “days” MissionTaskModel Mission Task Model A mission task is an entity that defines the conditions under which a reward will be given if the value of the associated counter exceeds a certain level.  missionTaskId string * ~ 1024 chars Mission Task A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. verifyCompleteType string (enum) enum {   “counter”,   “verifyActions” } “counter” Completion condition type Specifies how mission task completion is determined. “counter” checks if the associated counter’s scoped value reaches the target threshold. “verifyActions” uses verify actions to check completion conditions. Definition Description “counter” Counter “verifyActions” Verify Actions targetCounter TargetCounterModel {verifyCompleteType} == “counter”  Target Counter Defines the counter, scope, and target value used to determine mission task completion. When the counter’s scoped value reaches or exceeds the specified target value, the task is considered accomplished. * Required if verifyCompleteType is “counter” verifyCompleteConsumeActions List {verifyCompleteType} == “verifyActions” [] 0 ~ 10 items Verify Actions when task is accomplished A list of verify actions used to determine if the mission task is completed. All verify actions must pass for the task to be considered accomplished. Only used when verifyCompleteType is “verifyActions”. * Enabled only if verifyCompleteType is “verifyActions” completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. challengePeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with a set period of time during which rewards can be received Specifies the GS2-Schedule event that defines the time window during which the mission task rewards can be claimed. If not set, rewards can be received at any time after accomplishment. premiseMissionTaskName string ~ 128 chars Name of the task that must be accomplished to attempt this task Specifies a prerequisite mission task within the same group that must be completed before the player can receive the reward for this task. Used to create sequential mission chains. TargetCounterModel Target Counter Information about the counter that serves as the achievement goal for the mission  counterName string  ~ 128 chars Counter Model name Counter Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Specifies which type of counter scope to use for the mission completion check. “resetTiming” evaluates the counter value for a specific reset period, while “verifyAction” evaluates the value for a named condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming” Target Reset timing Specifies which reset timing scope of the counter to check against the target value. For example, selecting “daily” means the task checks the daily counter value. If omitted, the mission group’s reset timing is used. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Enabled only if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition scope to check against the target value. Must match a conditionName defined in the counter model’s scopes. Only used when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long  0 ~ 9223372036854775805 Target value The threshold value that the counter’s scoped value must reach or exceed for the mission task to be considered accomplished. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Mission Master Data Reference","url":"/api_reference/mission/master_data/"},{"content":"Master Data Format  version string  2024-06-20 Format version of master data storeContentModels List ~ 1000 items Store Content Model This is a model for storing content from various store platforms. storeSubscriptionContentModels List ~ 1000 items Store Subscription Content Model This is a model for storing subscription-based content from various store platforms. Models StoreContentModel Store Content Model This is a model for storing content from various store platforms.  storeContentModelId string * ~ 1024 chars Store Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Content Model name metadata string ~ 1024 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. appleAppStore AppleAppStoreContent Apple AppStore Content The Apple App Store product information (product ID) for this store content. Used during receipt verification to match the purchased product. googlePlay GooglePlayContent Google Play Content The Google Play product information (product ID) for this store content. Used during receipt verification to match the purchased product. AppleAppStoreContent Content of Apple AppStore Contains the Apple App Store product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Apple App Store product identifier registered in App Store Connect for this in-app purchase item. GooglePlayContent Content of Google Play Contains the Google Play product ID that corresponds to an in-app purchase product. Used to match receipts during verification.  productId string ~ 1024 chars Product ID The Google Play product identifier registered in Google Play Console for this in-app purchase item. StoreSubscriptionContentModel Store Subscription Content Model This is a model for storing subscription-based content from various store platforms.  storeSubscriptionContentModelId string * ~ 1024 chars Subscription Content Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Store Subscription Content Model name metadata string ~ 1024 chars Metadata scheduleNamespaceId string  ~ 1024 chars Namespace A unique resource name assigned to all information handled by GS2\" \u003e GRN of GS2-Schedule to link the subscription period triggerName string  ~ 128 chars Trigger name to reflect the subscription period The name of the GS2-Schedule trigger that will be activated to reflect the subscription’s active period. The trigger duration is set to the subscription’s expiration time. triggerExtendMode string (enum) enum {   “just”,   “rollupHour” } “just” Mode to reflect the subscription period on the trigger Controls how the subscription expiration is mapped to the trigger duration. “just” uses the exact subscription period. “rollupHour” extends the period to the next specified hour (UTC) to avoid mid-day expirations. Definition Description “just” Reflect the subscription period as it is “rollupHour” Extend the subscription period to the next day crossing time rollupHour int {triggerExtendMode} == “rollupHour” 0 0 ~ 23 Hour of the day to roll up the subscription period (UTC) When triggerExtendMode is “rollupHour”, the subscription period is extended to this hour (0-23, UTC) on the expiration day. This prevents subscriptions from expiring in the middle of a user’s play session. * Enabled only if triggerExtendMode is “rollupHour” reallocateSpanDays int 30 0 ~ 365 Time span (days) that allows subscription contract information to be assigned to other users The number of days after the last allocation before a subscription contract can be reassigned to a different user. This prevents abuse when users change accounts, by enforcing a waiting period before the subscription can be transferred. appleAppStore AppleAppStoreSubscriptionContent Apple AppStore Content The Apple App Store subscription information (subscription group identifier) for this subscription content. googlePlay GooglePlaySubscriptionContent Google Play Content The Google Play subscription information (product ID) for this subscription content. AppleAppStoreSubscriptionContent Subscription content of Apple AppStore Contains the Apple App Store subscription group identifier for subscription-based products. Used to manage and verify auto-renewable subscriptions.  subscriptionGroupIdentifier string ~ 64 chars Subscription Group ID The subscription group identifier registered in App Store Connect. Subscriptions within the same group are mutually exclusive, meaning a user can only subscribe to one at a time. GooglePlaySubscriptionContent Google Play Subscription Content Contains the Google Play product ID for subscription-based products. Used to manage and verify auto-renewable subscriptions on Google Play.  productId string ~ 1024 chars Product ID","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Money2 Master Data Reference","url":"/api_reference/money2/master_data/"},{"content":"Master Data Format  version string  2019-05-14 Format version of master data groups List ~ 10 items Quest Group Model A Quest Group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups. Models QuestGroupModel Quest Group Model A Quest Group is an entity for grouping multiple quests, and only one quest progression can be executed simultaneously within the group. This means that if you need to be able to progress quests in parallel, you must separate the groups.  questGroupModelId string * ~ 1024 chars Quest Group A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Group Model name Quest Group Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. quests List [] 0 ~ 1000 items Quests belonging to the group List of quest models that belong to this quest group. Only one quest within the group can be in progress at a time. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which quests in this group can be attempted. When specified, quests in this group can only be started while the event is active. QuestModel Quest Model A Quest Model is an entity that defines the cost required to start a quest and the rewards obtained upon completion. The reward obtained upon completion of the quest can have multiple variations and can be drawn at the start of the quest. For example, the same content can be used to manage the clear flag of a quest, but two types of content can be prepared based on whether or not a rare monster appears.  questModelId string * ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Quest Model name Quest Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. contents List [] 1 ~ 10 items Quest content variations List of content variations for this quest. When the quest starts, one variation is selected by weighted random draw. Each variation can define different completion rewards, allowing different outcomes (e.g., rare monster appearances) for the same quest. challengePeriodEventId string ~ 1024 chars Challenge Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that sets the time period during which this quest can be attempted. When specified, the quest can only be started while the event is active. This setting takes precedence over the quest group’s challenge period. firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. premiseQuestNames List [] 0 ~ 10 items Prerequisite Quest Names List of quest names within the same group that must be completed before this quest can be attempted. Used to create sequential quest chains or branching quest paths. Contents Contents Represents one variation of quest content. Each quest can have multiple content variations with different rewards, and one is selected by weighted random draw at quest start. The metadata supports template variable substitution with user ID and config values.  metadata string ~ 256 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. completeAcquireActions List [] 0 ~ 10 items Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. weight int 1 1 ~ 2147483646 Draw Weight The relative weight used in the random selection of this content variation at quest start. Higher values increase the probability of this variation being selected. For example, a variation with weight 9 is 9 times more likely to be selected than one with weight 1. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Quest Master Data Reference","url":"/api_reference/quest/master_data/"},{"content":"Master Data Format  version string  2019-09-17 Format version of master data categories List ~ 1000 items Category Model Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation. Models CategoryModel Category Model Different rankings can be created for different categories. Categories can have a minimum and maximum score that can be registered, and scores outside of that range are discarded. When calculating rankings, it is possible to set whether the scores are to be ranked in ascending or descending order, with the smallest scores being ranked higher (ascending order) or the largest scores being ranked lower (descending order). You can select global or scope as the type of ranking. Global is a ranking where all players see the same results, and Scope is a ranking where each game player has a different result, such as a ranking among friends or a ranking in a guild. For global ranking, you can set the ranking interval from 15 minutes to 24 hours for each category. Scope rankings reflect the calculate results in real time. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  categoryModelId string * ~ 1024 chars Category Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Category Model name Category Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Value The minimum score value that can be registered in this category. Scores below this threshold are rejected at registration time. If not set, there is no lower bound. maximumValue long 0 ~ 9223372036854775805 Maximum Value The maximum score value that can be registered in this category. Scores above this threshold are rejected at registration time. If not set, there is no upper bound. sum bool false Sum Mode When enabled, newly registered scores are added to the user’s existing score total rather than replacing it. The ranking is then based on the accumulated total. When disabled, each score registration is treated as an independent entry. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction Determines the sort order for ranking calculation. “asc” (ascending) ranks lower scores higher, suitable for time-based or golf-style rankings. “desc” (descending) ranks higher scores higher, suitable for point-based or high-score rankings. Definition Description “asc” ascending-order “desc” descending-order scope string (enum) enum {   “global”,   “scoped” }  Scope The type of ranking for this category. “global” creates a single leaderboard shared by all players, recalculated at configured intervals (batch processing). “scoped” creates per-user leaderboards based on subscribed players (e.g., friends or guild members), with real-time score reflection. Definition Description “global” Global “scoped” Scoped globalRankingSetting GlobalRankingSetting {scope} == “global”  Global Ranking Setting Configuration specific to global ranking mode, including calculation interval, fixed timing, score uniqueness, generation management, and additional time-windowed scopes. Only applicable when scope is set to “global”. * Required if scope is “global” entryPeriodEventId string ~ 1024 chars Entry Period Event ID GRN of a GS2-Schedule event that defines the time window during which score registration is accepted. Outside this period, score submission requests are rejected. If not set, scores can be registered at any time. accessPeriodEventId string ~ 1024 chars Access Period Event ID GRN of a GS2-Schedule event that defines the time window during which ranking data can be viewed. Outside this period, ranking retrieval requests are rejected. If not set, rankings can be accessed at any time. Scope Aggregation Scope Defines an additional time-windowed aggregation scope for Global Ranking mode. Normally, global ranking is calculated for all registered scores regardless of when they were submitted. By adding scopes, you can create separate rankings that only consider scores registered within a specified number of days, enabling daily, weekly, or monthly leaderboards alongside the all-time ranking.  name string  ~ 128 chars Scope Name A unique name identifying this aggregation scope within the category. Used to distinguish between multiple time-windowed ranking boards (e.g., “daily”, “weekly”). Maximum 128 characters. targetDays long  1 ~ 365 Target Days The number of days to include in the aggregation window. Only scores registered within this number of days from the current time are considered for the scoped ranking. Range: 1-365 days. GlobalRankingSetting Global Ranking Setting Global is a ranking where all players see the same results. The ranking interval can be set from 15 minutes to 24 hours. The ranking data has a setting called “generation,” and the registered scores can be reset by changing the generation.  uniqueByUserId bool true Unique By User ID When enabled, only one score per user ID is kept in the ranking. If a user submits a new score, it replaces the previous one (keeping the better score based on the sort direction). When disabled, multiple score entries from the same user are allowed, enabling sum-mode or multi-entry competition. calculateIntervalMinutes int  15 ~ 1440 Calculate Interval Minutes The interval in minutes between successive ranking recalculations. The system periodically recalculates the global ranking based on all registered scores at this interval. Range: 15 to 1440 minutes (15 minutes to 24 hours). calculateFixedTiming FixedTiming Calculate Fixed Timing Specifies a fixed time of day (UTC) at which ranking recalculation starts. If not set, recalculation occurs at regular intervals from an unspecified base time. Setting this ensures recalculations happen at a predictable, consistent time each day. additionalScopes List 0 ~ 10 items Additional Scopes A list of additional time-windowed aggregation scopes. Each scope defines a separate ranking that only considers scores registered within a specified number of days. This enables creating daily, weekly, or monthly leaderboards alongside the all-time global ranking. Maximum 10 scopes. ignoreUserIds List 0 ~ 10000 items Ignore User IDs A list of user IDs whose scores should be excluded from ranking calculation. Useful for filtering out test accounts, administrator accounts, or known cheaters from the leaderboard. Maximum 10,000 entries. generation string ~ 256 chars Generation An arbitrary string representing the current ranking generation. Changing this value effectively resets all registered scores, as scores from a previous generation are no longer included in ranking calculations. Useful for implementing seasonal resets or periodic ranking resets. Maximum 256 characters. FixedTiming Fixed Timing Specifies the fixed time of day at which global ranking calculations start. Without this setting, ranking calculation occurs at regular intervals from an unspecified base time. By specifying a fixed hour and minute, you can ensure that ranking recalculation always begins at a predictable time (in UTC), such as midnight or a specific hour.  hour int 0 ~ 23 Hour The hour (UTC) at which ranking calculation starts. Specified as an integer from 0 to 23. minute int 0 ~ 59 Minute The minute at which ranking calculation starts within the specified hour. Specified as an integer from 0 to 59.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Ranking Master Data Reference","url":"/api_reference/ranking/master_data/"},{"content":"Master Data Format  version string  2024-05-30 Format version of master data globalRankingModels List ~ 10 items Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. clusterRankingModels List ~ 10 items Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions. subscribeRankingModels List ~ 10 items Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking. Models GlobalRankingModel Global Ranking Model The global ranking is a model that allows you to create a ranking that targets all players. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  globalRankingModelId string * ~ 1024 chars Global Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. Used to filter out invalid or unintended score values. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. Used to prevent abnormally high scores from being registered. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score (highest or lowest depending on sort direction) is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for rankings where lower scores are better (e.g., time trials), or “desc” for rankings where higher scores are better (e.g., high scores). Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. Each reward defines a rank threshold and the acquire actions to execute. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. Typically set to the interval between score entry periods. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (players with tied scores share the same rank), while “index” uses the 0-based unique sorted position (no ties). Choose “rank” for most typical use cases. Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index RankingReward Ranking Reward Set the rewards that can be received during the reference period when the score registration period is set in the ranking. If the repeat setting is enabled, the most recently ended period ranking will be the target for receiving rewards.  thresholdRank int  1 ~ 1001 Rank Threshold The rank threshold for this reward tier. Players whose rank (or index, depending on rewardCalculationIndex setting) is at or above this threshold receive this reward. Set to 1001 to define rewards for unranked players (those outside the top 1000). metadata string ~ 1024 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. acquireActions List [] 0 ~ 100 items List of Acquire Actions List of acquire actions executed when the player claims this ranking reward. These define the actual items, currency, or other resources granted as the reward for achieving this rank threshold. AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action ClusterRankingModel Cluster Ranking Model The cluster ranking model enables rankings for players within guilds or gatherings. You can display the top 1000 rankings. By associating it with the repeat event of GS2-Schedule, you can reset the ranking according to the number of repetitions.  clusterRankingModelId string * ~ 1024 chars Cluster Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. clusterType string (enum) enum {   “Raw”,   “Gs2Guild::Guild”,   “Gs2Matchmaking::SeasonGathering” }  Cluster Type Defines the type of group (cluster) used for ranking segmentation. “Raw” allows arbitrary cluster names without membership verification, “Gs2Guild::Guild” verifies the user belongs to a GS2-Guild guild, and “Gs2Matchmaking::SeasonGathering” verifies membership in a GS2-Matchmaking season gathering. Definition Description “Raw” No verification “Gs2Guild::Guild” GS2-Guild Guild “Gs2Matchmaking::SeasonGathering” GS2-Matchmaking Season Gathering minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. rankingRewards List {entryPeriodEventId} != null [] 0 ~ 100 items Ranking Rewards List of rewards granted based on ranking position at the end of each season. Only available when an entry period event is configured. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed and rewards can be claimed. rewardCalculationIndex string (enum) enum {   “rank”,   “index” } “rank” Reward Calculation Index Determines how rewards are matched to players. “rank” uses the 1-based ranking position (tied scores share same rank), “index” uses the 0-based unique sorted position (no ties). Definition Description “rank” Determine rewards based on rank “index” Determine rewards based on index SubscribeRankingModel Subscribe Ranking Model A model that aggregates scores of other players that the user has subscribed to and creates a ranking.  subscribeRankingModelId string * ~ 1024 chars Subscribe Ranking A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 1024 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. minimumValue long 0 ~ 9223372036854775805 Minimum Score The minimum allowed score value. Scores below this value will be rejected when submitted. maximumValue long 0 ~ 9223372036854775805 Maximum Score The maximum allowed score value. Scores above this value will be rejected when submitted. sum bool false Sum Scores When enabled, all submitted scores are accumulated and the ranking is determined by the total value. When disabled, only the best score is used for ranking. orderDirection string (enum) enum {   “asc”,   “desc” }  Order Direction The sort direction for ranking scores. Use “asc” for lower-is-better rankings, or “desc” for higher-is-better rankings. Definition Description “asc” ascending-order “desc” descending-order entryPeriodEventId string ~ 1024 chars Entry Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which scores can be submitted. When linked to a repeating event, the ranking resets with each repeat cycle, enabling seasonal rankings. accessPeriodEventId string ~ 1024 chars Access Period Event A unique resource name assigned to all information handled by GS2\" \u003e GRN GS2-Schedule event GRN that defines the period during which ranking results can be viewed.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Ranking2 Master Data Reference","url":"/api_reference/ranking2/master_data/"},{"content":"Master Data Format  version string  2019-03-31 Format version of master data events List ~ 100 items Event Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period. Models Event Event Two types of event durations exist: absolute and relative. Absolute periods are fixed periods, for example, from YYYY-MM-DD 00:00 (UTC) to YYYY-MM-DD 23:59 (UTC). A relative period is an event period that varies from one game player to another, such as 24 hours from the time the trigger is activated. In addition to the event duration, a repeat pattern can also be configured. An event period can be set up so that only Monday from 10:00 to 11:00 is included in the event period.  eventId string * ~ 1024 chars GS2-Schedule Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Event name Event-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. scheduleType string (enum) enum {   “absolute”,   “relative” }  Schedule Type Determines how the event period is defined. “absolute” uses fixed start/end timestamps that are the same for all players. “relative” uses a per-player trigger as the starting point, enabling personalized event periods (e.g., 24 hours from when each player first logs in). Definition Description “absolute” Fixed period “relative” Player-specific period absoluteBegin long Absolute Begin The fixed start time of the event period for absolute scheduling. All players share the same start time. If not set for an absolute event, the event is considered to have started from the beginning of time. Expressed as Unix time in milliseconds. absoluteEnd long Absolute End The fixed end time of the event period for absolute scheduling. All players share the same end time. If not set for an absolute event, the event is considered to have no end. Expressed as Unix time in milliseconds. relativeTriggerName string {scheduleType} == “relative”  ~ 128 chars Event start trigger name Specify the name of the trigger that serves as the starting point for the event when setting an event period relative to each game player ( relative ). Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). * Required if scheduleType is “relative” repeatSetting RepeatSetting  Repeat Setting Configuration for recurring time windows within the event period. Allows narrowing the active period to specific hours, days of the week, days of the month, or custom active/inactive day cycles. Set repeatType to “always” to keep the event active throughout the entire event period without any repeating pattern. RepeatSetting Repeat Setting Configures a recurring time window within the overall event period. Supports five repeat types: “always” (entire event period), “daily” (specific hours each day), “weekly” (specific day-of-week range with hours), “monthly” (specific day-of-month range with hours), and “custom” (alternating active/inactive day cycles from an anchor date). When beginHour equals endHour for daily/weekly/monthly types, the end time is treated as the same hour on the following day (i.e., a full 24-hour window).  repeatType string (enum) enum {   “always”,   “daily”,   “weekly”,   “monthly”,   “custom” } “always” Repeat Type The type of repeat pattern to apply within the event period. Determines which additional fields are required: daily/weekly/monthly require hour settings, weekly requires day-of-week, monthly requires day-of-month, and custom requires anchor timestamp and day counts. Defaults to “always” if not specified. Definition Description “always” Always during the entire event period “daily” Every day during the event period from X:00 to X:00 “weekly” During the event period, every week from the start day to the end day, X:00 to X:00 “monthly” During the event period, every month from the start date to the end date, X:00 to X:00 “custom” Starting from the reference date, active for X days and inactive for Y days during the event period beginDayOfMonth int {repeatType} == “monthly”  1 ~ 31 Begin Day of Month The day of the month when the repeat window starts (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” endDayOfMonth int {repeatType} == “monthly”  1 ~ 31 End Day of Month The day of the month when the repeat window ends (1-31). If the specified value exceeds the number of days in a given month, it is treated as the last day of that month. Only applicable when repeatType is “monthly”. * Required if repeatType is “monthly” beginDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  Begin Day of Week The day of the week when the repeat window starts. The window can span across week boundaries (e.g., Friday to Monday). Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” endDayOfWeek string (enum) enum {   “sunday”,   “monday”,   “tuesday”,   “wednesday”,   “thursday”,   “friday”,   “saturday” } {repeatType} == “weekly”  End Day of Week The day of the week when the repeat window ends. Combined with beginDayOfWeek to define the weekly active period. Only applicable when repeatType is “weekly”. Definition Description “sunday” Sunday “monday” Monday “tuesday” Tuesday “wednesday” Wednesday “thursday” Thursday “friday” Friday “saturday” Saturday * Required if repeatType is “weekly” beginHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 23 Begin Hour The hour (UTC, 0-23) at which the repeat window starts each cycle. Required for daily, weekly, and monthly repeat types. If beginHour equals endHour, the window spans a full 24 hours (ending at the same hour the next day). * Required if repeatType is “daily”,“weekly”,“monthly” endHour int {repeatType} in [“daily”, “weekly”, “monthly”]  0 ~ 24 End Hour The hour (UTC, 0-24) at which the repeat window ends each cycle. A value of 24 represents midnight of the following day. Required for daily, weekly, and monthly repeat types. * Required if repeatType is “daily”,“weekly”,“monthly” anchorTimestamp long {repeatType} == “custom”  Anchor Timestamp The reference date from which the custom active/inactive cycle begins. The system calculates which phase (active or inactive) the current time falls into based on elapsed days from this anchor. Only applicable when repeatType is “custom”. Expressed as Unix time in milliseconds. * Required if repeatType is “custom” activeDays int {repeatType} == “custom”  1 ~ 2147483646 Active Days The number of consecutive days the event is active in each custom cycle. After these active days, the event becomes inactive for the number of days specified by inactiveDays, then the cycle repeats. Only applicable when repeatType is “custom”. Minimum 1 day. * Required if repeatType is “custom” inactiveDays int {repeatType} == “custom”  0 ~ 2147483646 Inactive Days The number of consecutive days the event is inactive in each custom cycle. Follows the active days period. Set to 0 for a continuously active event with no gaps. Only applicable when repeatType is “custom”. Minimum 0 days. * Required if repeatType is “custom”","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Schedule Master Data Reference","url":"/api_reference/schedule/master_data/"},{"content":"Master Data Format  version string  2024-02-23 Format version of master data seasonModels List ~ 50 items Season Model Defines the tier structure and point adjustment rules applied during a season. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience. Models SeasonModel Season Model Defines the tier structure and point adjustment rules applied during a season. Specifies tier-based point change ranges, entry fees, rank-up bonuses, and the Experience Model used for point management. Actual user data (points and tier affiliation) is managed by GS2-Experience.  seasonModelId string * ~ 1024 chars Season Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. tiers List  1 ~ 100 items List of Tier Models The ordered list of tier definitions that compose the season’s ranking ladder. Each tier defines its own point adjustment rules (entry fee, min/max change, rank-up bonus). Players progress through tiers based on their accumulated points managed by GS2-Experience. Minimum 1 tier, maximum 100 tiers. experienceModelId string  ~ 1024 chars Experience Model ID GRN of the GS2-Experience experience model used to manage season points and tier progression. The experience model’s rank thresholds determine tier boundaries, and experience values represent the player’s current season points. Point changes from match results are applied to this experience model. challengePeriodEventId string ~ 1024 chars Challenge Period Event ID GRN of the GS2-Schedule event that defines the period during which the season is open for competitive matches. When set, players can only participate in matches while the referenced event is active. If not set, the season has no time restriction. TierModel Tier Model TierModel defines the point adjustment rules for each tier within a season. Specifies point change ranges by rank, entry fees, and promotion bonuses. While actual point data is managed by GS2-Experience, the calculation logic for point adjustments is determined by the TierModel configuration.  metadata string ~ 128 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. raiseRankBonus int  0 ~ 10000 Raise Rank Bonus Bonus points added when a player is promoted to this tier, providing a buffer to prevent immediate demotion. For example, if set to 100, the player starts the new tier with 100 extra points above the promotion threshold. Valid range: 0 to 10000. entryFee int  0 ~ 10000 Entry Fee Points deducted from the player before the match begins as a participation cost. This fee is always subtracted regardless of the match outcome, creating a risk element in competitive play. Valid range: 0 to 10000. minimumChangePoint int  -99999999 ~ -1 Minimum Change Point The minimum (most negative) point change that can occur from a single match result, typically representing the worst-case loss. Must be a negative value. The actual point change for a losing player falls between this value and 0. Valid range: -99999999 to -1. maximumChangePoint int  1 ~ 99999999 Maximum Change Point The maximum (most positive) point change that can occur from a single match result, typically representing the best-case win. Must be a positive value. The actual point change for a winning player falls between 0 and this value. Valid range: 1 to 99999999.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-SeasonRating Master Data Reference","url":"/api_reference/season_rating/master_data/"},{"content":"Master Data Format  version string  2022-09-13 Format version of master data campaignModels List ~ 1000 items Campaign Model A Campaign Model is used to define and manage campaigns, linking them to serial codes. Models CampaignModel Campaign Model A Campaign Model is used to define and manage campaigns, linking them to serial codes.  campaignId string * ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the Campaign Model * Set automatically by the server name string  ~ 128 chars Campaign Model name 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. enableCampaignCode bool false Whether to allow redemption with campaign code When enabled, users can redeem rewards using a shared campaign code (the campaign name) instead of individual serial codes. This allows a single code to be used by multiple users.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-SerialKey Master Data Reference","url":"/api_reference/serial_key/master_data/"},{"content":"Master Data Format  version string  2019-04-04 Format version of master data showcases List ~ 100 items Showcase A Showcase can define items for display. Additionally, the sales period for items on Showcase can be set. randomShowcases List ~ 100 items Random Showcase Random Showcase is a display model featuring randomly selected display items that rotate at specified intervals. The display item to be selected are randomly selected from the registered display items in the display item pool according to the specified quantity and the weight set for each display item. By associating a GS2-Schedule event with the Random Showcase, you can set its sales period. Models Showcase Showcase A Showcase can define items for display. Additionally, the sales period for items on Showcase can be set.  showcaseId string * ~ 1024 chars Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Showcase name Showcase-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. salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Showcase Controls the overall sales period of this showcase. When specified, the entire showcase is only available during the associated GS2-Schedule event period. If the event is not active, the showcase returns empty. displayItems List [] 1 ~ 1000 items List of Display Items The list of items displayed on this showcase. Each display item can be either a single sales item or a sales item group. Items with an expired or inactive sales period event are automatically filtered out when the showcase is retrieved. DisplayItem Displayed Item An item displayed on a showcase. Can reference either a single sales item or a sales item group. Each display item can have its own sales period controlled by a GS2-Schedule event, independently of the showcase-level sales period.  displayItemId string  UUID ~ 128 chars Displayed Item ID Maintains a unique name for displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. type string (enum) enum {   “salesItem”,   “salesItemGroup” }  Type The type of item displayed. A “salesItem” is a single Sales Item with fixed price and rewards. A “salesItemGroup” contains multiple Sales Items evaluated in order, used for step-up pricing or limited purchase discounts. Definition Description “salesItem” Sales Item “salesItemGroup” Sales Item Group salesItem SalesItem {type} == “salesItem”  Sales Item * Required if type is “salesItem” salesItemGroup SalesItemGroup {type} == “salesItemGroup”  Sales Item Group * Required if type is “salesItemGroup” salesPeriodEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN with sales periods for this display item Controls the sales period of this individual display item. When specified, the item is only shown on the showcase during the associated GS2-Schedule event period. This is independent of the showcase-level sales period. SalesItem Sales Item Defines the price required to purchase a Sales Item and the rewards granted upon purchase.  name string  ~ 128 chars Sales Item name Sales Item-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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. SalesItemGroup Sales Item Group A Sales Item Group is an entity for display on a Showcase. Multiple Sales Items can belong to a Sales Item Group. Sales Items are evaluated in order, and the first Sales Item determined to be available for purchase is displayed on the Showcase. This can be used for Sales Items that are discounted only for the first purchase, or for systems where the contents change based on the number of purchases, such as a step-up gacha.  name string  ~ 128 chars Sales Item Group name Sales Item Group-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. salesItems List [] 2 ~ 10 items Sales Items included in the Sales Item Group Ordered list of sales items in this group. The system evaluates each item from first to last using GS2-Limit counters to determine purchase availability. The first purchasable item is displayed; if none qualify, the last item in the list is used as a fallback. ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action RandomShowcase Random Showcase Random Showcase is a display model featuring randomly selected display items that rotate at specified intervals. The display item to be selected are randomly selected from the registered display items in the display item pool according to the specified quantity and the weight set for each display item. By associating a GS2-Schedule event with the Random Showcase, you can set its sales period.  randomShowcaseId string * ~ 1024 chars Random Showcase A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Random Showcase name Random Showcase-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. maximumNumberOfChoice int  1 ~ 100 Maximum number of display items to be selected The number of display items randomly drawn from the display item pool each rotation period. Items are drawn without replacement using weighted random selection, so the same item will not appear twice in one rotation. displayItems List [] 1 ~ 100 items List of Display Items subject to selection The pool of candidate display items from which items are randomly drawn. Each item has a weight that determines its relative selection probability and a stock count that limits how many times it can appear across rotations. baseTimestamp long  Base time for re-drawing the display items on display The reference timestamp used to calculate rotation boundaries. display item re-draws occur at regular intervals (resetIntervalHours) starting from this base time. Must be set to a past timestamp. resetIntervalHours int  1 ~ 168 Interval (hours) between re-drawing the display items on display The number of hours between each display item rotation. When the interval elapses (relative to baseTimestamp), the display items are re-drawn with a new random seed. Can be set from 1 to 168 hours (1 week). salesPeriodEventId string ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN of the GS2-Schedule event that defines the sales period for the Random Showcase Controls the overall sales period of this random showcase. When specified, the showcase is only available during the associated GS2-Schedule event period. RandomDisplayItemModel Items that can be displayed in a Random Showcase You can set the probability of selecting each item with weight .  name string  UUID ~ 128 chars Random Displayed Item ID Maintains a unique name for randomly displayed Sales Items. If omitted, the system automatically assigns a name in UUID (Universally Unique Identifier) format. 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. verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before purchasing this Random Displayed Item. All verify actions must pass before consume and acquire actions are processed. consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price for this Random Displayed Item. Executed as consume actions in the transaction. acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards for this Random Displayed Item. Executed as acquire actions in the transaction. stock int  1 ~ 2147483646 Stock The maximum number of times this item can be drawn across all rotations. Once stock reaches zero, the item is excluded from future draws. Stock is consumed when the item is selected during a rotation draw. weight int  1 ~ 2147483646 Draw Weight The relative probability weight for this item in the random selection. Higher weights increase the chance of being drawn. The actual selection probability is calculated as this item’s weight divided by the sum of all eligible items’ weights.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Showcase Master Data Reference","url":"/api_reference/showcase/master_data/"},{"content":"Master Data Format  version string  2023-09-06 Format version of master data nodeModels List ~ 1000 items Node Model Defines a node within the skill tree, including its unlock cost, prerequisites, and refund behavior. Each node can have verify actions (conditions to check before release), consume actions (costs to pay), and prerequisite nodes that must be released first. When a node is restrained (reverted to unreleased), the consumed resources are partially refunded based on the restrain return rate. The return acquire actions are automatically calculated from the consume actions multiplied by the restrain return rate. Models NodeModel Node Model Defines a node within the skill tree, including its unlock cost, prerequisites, and refund behavior. Each node can have verify actions (conditions to check before release), consume actions (costs to pay), and prerequisite nodes that must be released first. When a node is restrained (reverted to unreleased), the consumed resources are partially refunded based on the restrain return rate. The return acquire actions are automatically calculated from the consume actions multiplied by the restrain return rate.  nodeModelId string * ~ 1024 chars Node Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Node Model name Node 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. releaseVerifyActions List [] 0 ~ 10 items List of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. returnAcquireActions List 0 ~ 10 items Return Acquire Actions List of acquire actions executed when restraining (reverting) this node, representing the resources returned to the player. This field is auto-generated from the release consume actions multiplied by the restrain return rate. For example, if release costs 100 gold and the return rate is 0.8, restraining returns 80 gold. Maximum 10 actions. restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. premiseNodeNames List [] 0 ~ 10 items List of Premise Node Names Names of other node models that must be released before this node can be unlocked. Defines the dependency graph of the skill tree. A node cannot be released unless all its prerequisite nodes are already released. Maximum 10 prerequisite nodes. ConsumeAction Consume Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action VerifyAction Verify Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action AcquireAction Acquire Action  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 request string  ~ 524288 chars JSON string of the request used when executing the action","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-SkillTree Master Data Reference","url":"/api_reference/skill_tree/master_data/"},{"content":"Master Data Format  version string  2019-02-14 Format version of master data staminaModels List ~ 100 items Stamina Model Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience. Models StaminaModel Stamina Model Parameters such as the maximum value of stamina, recovery interval, and amount of recovery can be defined. You can also control the maximum value and the amount of recovery in conjunction with GS2-Experience.  staminaModelId string * ~ 1024 chars Stamina Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Stamina Model name Stamina Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. recoverIntervalMinutes int  0 ~ 2147483646 Recover Interval Minutes The number of minutes between each stamina recovery tick. Every time this interval elapses, the player’s stamina increases by the recover value amount. Can be overridden per-user via GS2-Experience rank using a RecoverIntervalTable. Set to 0 to disable automatic time-based recovery. recoverValue int 1 0 ~ 2147483646 Recover Value The amount of stamina recovered per recovery tick. Each time the recover interval elapses, stamina increases by this value until the maximum is reached. Can be overridden per-user via GS2-Experience rank using a RecoverValueTable. Defaults to 1. initialCapacity int  0 ~ 2147483646 Initial Capacity The default maximum stamina value for all players. When overflow is disabled, this serves as the floor for the per-user maximum value. Can be overridden per-user via GS2-Experience rank using a MaxStaminaTable. isOverflow bool  Is Overflow Whether stamina can exceed the initial capacity through means such as item usage. When enabled, stamina can be set above initialCapacity up to maxCapacity. Natural time-based recovery still caps at the normal maximum. When disabled, the per-user maximum value is clamped to at least initialCapacity. maxCapacity int {isOverflow} == true  0 ~ 2147483646 Max Capacity The absolute upper limit of stamina when overflow is enabled. Even with overflow, stamina cannot exceed this value. Only shown when isOverflow is true. For example, if initialCapacity is 100 and maxCapacity is 200, items can boost stamina up to 200 but natural recovery stops at 100. * Required if isOverflow is true maxStaminaTable MaxStaminaTable Max Stamina Table Reference to a MaxStaminaTable that dynamically determines the maximum stamina value based on the player’s GS2-Experience rank. When set, the player’s max stamina is looked up from the table using their current rank index, overriding initialCapacity. If not set, all players share the same initialCapacity as their maximum. recoverIntervalTable RecoverIntervalTable Recover Interval Table Reference to a RecoverIntervalTable that dynamically determines the recovery interval based on the player’s GS2-Experience rank. When set, the player’s recovery interval is looked up from the table using their current rank index, overriding recoverIntervalMinutes. If not set, all players share the same recoverIntervalMinutes. recoverValueTable RecoverValueTable Recover Value Table Reference to a RecoverValueTable that dynamically determines the recovery amount based on the player’s GS2-Experience rank. When set, the player’s recovery value is looked up from the table using their current rank index, overriding recoverValue. If not set, all players share the same recoverValue. MaxStaminaTable Maximum Stamina Table This entity defines the maximum value of stamina for each rank of GS2-Experience.  name string  ~ 128 chars Maximum Stamina Table Name Maximum Stamina Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user maximum stamina. values List  1 ~ 1024 items Maximum Stamina Values by Rank An array of maximum stamina values indexed by the player’s GS2-Experience rank index. The value at index i is used as the maximum stamina for players at rank i. The array length should match the number of ranks defined in the referenced ExperienceModel. RecoverIntervalTable Recovery Interval Table This entity defines the stamina recovery interval for each rank of GS2-Experience.  name string  ~ 128 chars Stamina recovery interval table name Stamina recovery interval table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery interval. values List  1 ~ 1024 items Recovery Interval Values by Rank An array of recovery interval values (in minutes) indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery interval for players at rank i, overriding the model’s default recoverIntervalMinutes. RecoverValueTable Stamina Recovery Amount Table This entity defines the amount of stamina recovery for each rank of GS2-Experience.  name string  ~ 128 chars Stamina Recovery Amount Table name Stamina Recovery Amount Table-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). metadata string ~ 128 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. experienceModelId string  ~ 1024 chars Experience Model ID The GRN of the GS2-Experience ExperienceModel used to look up the player’s current rank. The rank index is used as an array index into the values list to determine the per-user recovery amount. values List  1 ~ 1024 items Recovery Amount Values by Rank An array of recovery amount values indexed by the player’s GS2-Experience rank index. The value at index i is used as the recovery amount per tick for players at rank i, overriding the model’s default recoverValue.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Stamina Master Data Reference","url":"/api_reference/stamina/master_data/"},{"content":"Master Data Format  version string  2019-10-09 Format version of master data versionModels List ~ 100 items Version Model You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version. Models VersionModel Version Model You can set a warning version that accepts login but notifies you that you can upgrade, and an error version that does not accept login. You can specify whether or not to have the client declare the current version with or without a signature. If you select signed, the client will not be able to declare a false version.  versionModelId string * ~ 1024 chars Version Model A unique resource name assigned to all information handled by GS2\" \u003e GRN * Set automatically by the server name string  ~ 128 chars Version Model name Version 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. scope string (enum) enum {   “passive”,   “active” }  Type of version value used for judgment Determines how the version value is obtained for checking. “passive” means the client declares its current version at check time, while “active” means the system uses a version the user has explicitly approved in the past (such as agreeing to terms of service). Definition Description “passive” Sent by Client “active” Version explicitly approved in the past type string (enum) enum {   “simple”,   “schedule” } “simple” Version Check Mode Selects the version checking strategy. “simple” uses fixed warning and error version thresholds, while “schedule” allows different version thresholds to be activated at different times using GS2-Schedule events. Definition Description “simple” Simple “schedule” Schedule Change currentVersion Version {type} == “simple” and {scope} == “active”  Current Version The latest version available for this version model. Used only with “active” scope in “simple” mode to inform users of the current version when they approve or review version updates. * Required if type is “simple” and scope is “active” warningVersion Version {type} == “simple”  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification. If the client’s version is below this value, login is still allowed but the user is prompted to upgrade. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” errorVersion Version {type} == “simple”  Version that is determined to be an error by the version check The minimum version threshold for allowing login. If the client’s version is below this value, the version check results in an error and login is blocked. Comparison is performed hierarchically: major, then minor, then micro. * Required if type is “simple” scheduleVersions List {type} == “schedule” 0 ~ 10 items List of Version check content that switches over time series A list of version check configurations that activate at different times based on GS2-Schedule events. This allows gradual version enforcement, such as showing warnings before making an update mandatory. * Enabled only if type is “schedule” needSignature bool {scope} == “passive”  Whether the version value to be determined requires signature verification When enabled, the client must provide a cryptographic signature along with the version declaration. This prevents clients from falsely reporting a higher version to bypass version checks. Only applicable when scope is “passive”. * Required if scope is “passive” signatureKeyId string {needSignature}  ~ 1024 chars Encryption Key A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if needSignature is “true” approveRequirement string (enum) enum {   “required”,   “optional” } {scope} == “active” “required” Requirement for approval Controls whether user approval is mandatory or optional for this version model. When “required”, the version check fails if the user has not approved the current version. When “optional”, the version check passes regardless of approval status. Only applicable when scope is “active”. Definition Description “required” Approval required “optional” Approval optional * Enabled only if scope is “active” Version Version Represents a version number with a three-level hierarchy (major, minor, micro). Version comparison is performed hierarchically: major version is compared first, then minor, then micro. Used to define warning and error thresholds for version checking.  major int  0 ~ 2147483646 Major version The highest priority component in version comparison. A difference in major version takes precedence over minor and micro versions. minor int  0 ~ 2147483646 Minor version The second priority component in version comparison. Compared only when the major versions are equal. micro int  0 ~ 2147483646 Micro version The lowest priority component in version comparison. Compared only when both major and minor versions are equal. ScheduleVersion Version that switches in chronological order Defines a set of version thresholds (current, warning, error) that become active during a specific time period controlled by a GS2-Schedule event. Multiple schedule versions can be configured to implement gradual version enforcement, such as warning users before blocking outdated clients.  currentVersion Version  Current Version The latest version available during this schedule period. Used with “active” scope to inform users of the current version when approving updates. warningVersion Version  Version that prompts for version upgrade The minimum version threshold for showing an upgrade notification during this schedule period. Login is allowed but the user is prompted to upgrade. errorVersion Version  Version that is determined to be an error by the version check The minimum version threshold for allowing login during this schedule period. If the client’s version is below this value, the version check results in an error and login is blocked. scheduleEventId string ~ 1024 chars GS2-Schedule event A unique resource name assigned to all information handled by GS2\" \u003e GRN that enables version check Specifies the GS2-Schedule event that controls when this set of version thresholds is active. The version check configuration defined here only applies during the period when the specified event is active.","lang":"en","section":"api_reference","summary":"Reference for the master data format and the models to be imported\n","title":"GS2-Version Master Data Reference","url":"/api_reference/version/master_data/"},{"content":"The sharing process is quite straightforward. Simply apply the GS2-Deploy template you developed to build your development and testing environment to your production GS2 Account project. If there are disruptive changes that would make the application incompatible, you may need to use GS2-Version + GS2-Gateway to disconnect the players, but that is also just an API call. See here for instructions on how to do this.","lang":"en","section":"overview","summary":"How to release a game using GS2.\n","title":"Release","url":"/overview/workflow/release/"},{"content":"Data analysis is important for the realization of Game as a Service. How many players are playing every day? Where are players getting stuck in the game? Is the game’s resource supply adequate? The more data you have, the more accurately you can determine what steps to take next to delight your players. Unlike many game-specific backend as a service approaches, GS2 does not store user data in simple binary storage. One of the reasons GS2 has time-consuming, function-specific microservices and stores data in each microservice is for data analysis. Game developers simply use GS2-Quest to manage the progress of their games, and GS2 does the data analysis and provides them with the number of attempts and percentage of quests completed through the management console. GS2 access logs are delivered in real time to your preferred Google BigQuery or [Amazon Kinesis Data Firehose]( https://aws.amazon.com/ kinesis/data-firehose/). The delivered access logs can be analyzed for your preferred data analysis. In addition, GS2 provides an open source GS2-Insight for visualizing data stored in Google BigQuery. This open source allows you to view metrics that are more detailed than those available in the management console and to visualize player behavior as a timeline.","lang":"en","section":"overview","summary":"How to analyze game data using GS2.\n","title":"Analysis","url":"/overview/workflow/analytics/"},{"content":"Consume Action Gs2AdReward:ConsumePointByUserId Consume Points by specifying a user ID Subtracts a specified number of points from the specified user ID and returns the updated point information. An error is returned if the user does not have enough points to cover the requested consumption amount. If a GS2-Script is configured in the namespace’s consume script settings, the script is executed before the point deduction, allowing custom validation or modification of the consume amount. After the point deduction, a change notification is sent if configured in the namespace settings. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. point long  1 ~ 9223372036854775805 Consume Points timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2AdReward:AcquirePointByUserId Acquire Points by specifying a user ID Adds a specified number of points to the specified user ID and returns the updated point information. If the user has no existing point record, a new record is automatically created before adding points. If a GS2-Script is configured in the namespace’s acquire script settings, the script is executed before the point addition, allowing custom validation or modification of the acquire amount. After the point addition, a change notification is sent if configured in the namespace settings. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. point long  1 ~ 9223372036854775805 Acquire Points timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-AdReward Transaction Actions","url":"/api_reference/ad_reward/stamp_sheet/"},{"content":"Verify Action Gs2Dictionary:VerifyEntryByUserId Verify Entry by specifying a user ID Verifies whether the specified user has or has not collected a specific entry. The verify type specifies the condition: ‘have’ checks that the user has the entry, ‘havent’ checks that the user does not have it. If the verification fails, an error is returned. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. entryModelName string  ~ 128 chars Entry Model name Entry Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). verifyType string (enum) enum {   “havent”,   “have” }  Type of verification Definition Description “havent” The specified entry must not be held “have” The specified entry must be held timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Dictionary:DeleteEntriesByUserId Delete entries by specifying a user ID Removes specific entries from the specified user’s dictionary by specifying a list of entry model names. Multiple entries can be deleted at once in a batch operation. The returned list contains the entries that were actually deleted. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Dictionary:AddEntriesByUserId Add entries by specifying a user ID Registers one or more entry model names to the specified user’s dictionary. Multiple entry model names can be specified at once in a batch operation. If an entry has already been registered, it is silently skipped without causing an error. The returned list contains only the entries that were newly added. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. entryModelNames List [] 0 ~ 100 items List of Entry Model names timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Dictionary Transaction Actions","url":"/api_reference/dictionary/stamp_sheet/"},{"content":"Verify Action Gs2Distributor:IfExpressionByUserId Validate the condition and switch the contents of the Consume Action Evaluates a verify action as a condition, and executes either the trueActions or falseActions list of consume actions based on the result. This enables conditional branching within a transaction, allowing different consume actions to be executed depending on the verification outcome. When multiplyValueSpecifyingQuantity is enabled, the values used for verification are also multiplied by the specified quantity. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. condition VerifyAction  Condition trueActions List 0 ~ 10 items List of Consume Actions to be executed when the condition is true falseActions List 0 ~ 10 items List of Consume Actions to be executed when the condition is false multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Distributor:AndExpressionByUserId Perform multiple verification actions and determine if all are true Executes multiple verify actions and succeeds only if all of them evaluate to true (AND logic). If any verify action fails, the entire expression fails. This is useful for combining multiple preconditions that must all be satisfied before proceeding with a transaction. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. actions List 0 ~ 10 items List of Verify Actions timeOffsetToken string ~ 1024 chars Time offset token Gs2Distributor:OrExpressionByUserId Perform multiple verification actions and determine if any are true Executes multiple verify actions and succeeds if at least one of them evaluates to true (OR logic). The expression fails only if all verify actions fail. This is useful for defining alternative conditions where satisfying any one of them is sufficient to proceed. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. actions List 0 ~ 10 items List of Verify Actions timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Distributor Transaction Actions","url":"/api_reference/distributor/stamp_sheet/"},{"content":"Verify Action Gs2Enchant:VerifyRarityParameterStatusByUserId Verify rarity parameter by specifying a user ID Verifies that a rarity parameter status of the specified user meets the specified condition. Three verification types are supported: ‘have’: Verifies that the specified parameter value exists in the status ‘havent’: Verifies that the specified parameter value does not exist in the status ‘count’: Verifies that the number of parameters matches the specified count This can be used as a precondition check before executing other actions. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. verifyType string (enum) enum {   “havent”,   “have”,   “count” }  Type of verification Definition Description “havent” The specified parameter must not be held “have” The specified parameter must be held “count” The number of parameters held must be the specified number parameterValueName string {verifyType} in [“havent”, “have”]  ~ 64 chars Name The identifier for this lottery entry. Must be unique within the rarity parameter model’s value pool. When drawn, this name is stored in the resulting Rarity Parameter Value. * Required if verifyType is “havent”,“have” parameterCount int {verifyType} in [“count”]  0 ~ 10 Number of parameters to verify multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Enchant:ReDrawBalanceParameterStatusByUserId Re-draw balance parameter by specifying a user ID Re-draws the balance parameter values for a specific property, redistributing the total value among the parameters. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). The total value constraint is maintained: the sum of all parameter values (including fixed ones) always equals the model’s total value. Both the updated and previous parameter states are returned. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. fixedParameterNames List [] 0 ~ 10 items List of Parameter index not to re-draw timeOffsetToken string ~ 1024 chars Time offset token Gs2Enchant:SetBalanceParameterStatusByUserId Set any value to Balance Parameter Status by specifying a user ID Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned. Both the updated and previous parameter states are returned. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. parameterName string  ~ 128 chars Balance Parameter Model name The name of the Balance Parameter Model that defines the drawing conditions for this status. References the model that specifies the total value, allocation strategy, and available parameter slots. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these balance parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List  1 ~ 10 items List of balance parameter values The concrete values assigned to each parameter slot after the drawing process. Each entry corresponds to a parameter slot defined in the model and contains the actual numeric value allocated. The sum of all values equals the total value specified in the model. timeOffsetToken string ~ 1024 chars Time offset token Gs2Enchant:ReDrawRarityParameterStatusByUserId Re-draw Rarity Parameter Status by specifying a user ID Re-draws the rarity parameter values for a specific property, randomly assigning new values based on the rarity weights. Specific parameters can be fixed (locked) to prevent them from being re-drawn by specifying their names in fixedParameterNames (up to 10). Fixed parameters retain their current values while unfixed parameters are re-drawn. Both the updated and previous parameter states are returned. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. fixedParameterNames List 0 ~ 10 items List of Parameter index not to re-draw timeOffsetToken string ~ 1024 chars Time offset token Gs2Enchant:AddRarityParameterStatusByUserId Add Rarity Parameter to status by specifying a user ID Adds new parameter slots to an existing rarity parameter status by randomly drawing values based on the rarity weights. The count specifies how many parameter slots to add (1 to 10), up to the model’s maximum parameter count. Both the updated and previous parameter states are returned. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. count int 1 1 ~ 10 Number of parameters to add timeOffsetToken string ~ 1024 chars Time offset token Gs2Enchant:SetRarityParameterStatusByUserId Set any value to rarity parameter by specifying a user ID Directly sets parameter values for a specific property of the specified user, bypassing the normal draw/re-draw mechanism. This is an administrative operation that allows arbitrary parameter values to be assigned regardless of rarity weights. Both the updated and previous parameter states are returned. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. parameterName string  ~ 128 chars Rarity Parameter Model name The name of the Rarity Parameter Model that defines the drawing conditions for this status. References the model that specifies the maximum parameter count, count lottery weights, and value lottery pool. propertyId string  ~ 1024 chars Property ID of the resource that owns the parameter Identifies the specific game resource (e.g., a weapon or equipment item) to which these rarity parameters are attached. Typically references a GS2-Inventory item or similar resource via its property ID. parameterValues List 0 ~ 10 items List of rarity parameter values The concrete parameter values selected through weighted lottery for each granted slot. The number of entries is determined by the parameter count draw, and each entry’s value is selected from the value model pool. May contain fewer entries than the maximum parameter count. timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Enchant Transaction Actions","url":"/api_reference/enchant/stamp_sheet/"},{"content":"Consume Action Gs2Enhance:DeleteProgressByUserId Delete running enhancement by specifying a user ID Deletes the progress record of the enhancement currently in progress for the specified user. This cancels the ongoing 2-phase enhancement, discarding the pre-calculated experience and bonus rate. Materials that were already consumed during the Start phase are not automatically refunded. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Enhance:DirectEnhanceByUserId Perform enhancement by specifying a user ID Consumes the specified materials to grant experience to the target item set based on the Enhanced Rate Model. The experience gained is calculated from the materials according to the experience hierarchy defined in the rate model, and a bonus rate is drawn from the configured bonus rate probability table. The result includes the acquired experience amount and the bonus rate applied. A transaction (transaction) is issued to execute the material consumption and experience acquisition. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List  1 ~ 10 items List of Material config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Gs2Enhance:UnleashByUserId Perform unleash by specifying a user ID Used for enhancement processing to raise the grade of the resource managed by GS2-Grade. In particular, it is used for the type of unleash that raises the level cap by consuming the same type of item as a material. Instead of consuming the specified material, the grade of the resource to be unleashed can be increased by 1. Even if the material resource has a resource such as experience value, the resource will not be inherited. If inheritance is required, the resource must be converted to a resource for inheritance in advance. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Enhancement Rate Model name Enhancement Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the Item Set subject to limit break materials List  1 ~ 1000 items List of materials that break the limit config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Gs2Enhance:CreateProgressByUserId Start enhancement by specifying a user ID Creates a progress record for a 2-phase enhancement flow. Validates the target item set and materials against the rate model, calculates the experience to be gained from the materials, and draws a bonus rate from the probability table. The calculated experience and bonus rate are stored in the progress record for later use when the enhancement is completed via the End API. If force is true, any existing progress for the user will be discarded and replaced. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. rateName string  ~ 128 chars Enhancement Rate Model name The name of the Enhancement Rate Model that defines the parameters for this enhancement operation. References the model that specifies the target inventory, material inventory, experience hierarchy, and bonus rates. targetItemSetId string  ~ 1024 chars A unique resource name assigned to all information handled by GS2\" \u003e GRN for the enhanced Item Set materials List 0 ~ 10 items List of materials force bool false If there is an enhancement that has already been started, it can be discarded and started, or timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Enhance Transaction Actions","url":"/api_reference/enhance/stamp_sheet/"},{"content":"Consume Action Gs2Exchange:DeleteAwaitByUserId Delete Exchange Await by specifying a user ID Deletes an exchange await record for the specified user. This cancels the pending exchange, and any rewards that have not yet been acquired are forfeited. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Exchange:ExchangeByUserId Perform exchange by specifying a user ID Executes a resource exchange based on the specified Exchange Rate Model for the specified user. Validates the rate model’s timing type: for ‘immediate’ timing, the namespace must have direct exchange enabled; for ‘await’ timing, the namespace must have await exchange enabled. A transaction (transaction) is issued to execute the consume/verify/acquire actions defined in the rate model, multiplied by the specified count. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Gs2Exchange:IncrementalExchangeByUserId Perform incremental cost exchange by specifying a user ID Executes a resource exchange where the cost increases progressively with each execution, based on the specified Incremental Cost Exchange Rate Model for the specified user. The consume cost is calculated according to the model’s calculation type (linear formula or GS2-Script) and the current exchange count. A transaction (transaction) is issued to execute the consume and acquire actions. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rateName string  ~ 128 chars Incremental Cost Exchange Rate Model name Incremental Cost Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. count int  1 ~ 1073741821 Number of exchanges config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Gs2Exchange:CreateAwaitByUserId Create Exchange Await by specifying a user ID Creates a new exchange await record for a time-delayed exchange. The specified rate model must have its timing type set to ‘await’; otherwise the request is rejected. The await starts with zero skip seconds, and the lock time defined in the rate model determines how long the user must wait before acquiring the rewards. Default configuration values can be set at creation time and will be merged with any config provided at acquisition time. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. rateName string  ~ 128 chars Exchange Rate Model name Exchange Rate Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). count int 1 1 ~ 10000 Number of exchanges The number of times this exchange should be performed. Multiple exchanges can be batched into a single await, multiplying both the cost consumed and the rewards received. config List [] 0 ~ 32 items Default configuration values applied when obtaining rewards timeOffsetToken string ~ 1024 chars Time offset token Gs2Exchange:AcquireForceByUserId Receive rewards for Exchange Await without waiting for the lock time Force-acquires the rewards for an exchange await regardless of whether the lock time has elapsed. This bypasses the normal wait time check, allowing immediate reward acquisition. The provided config values are merged with the default config set at await creation time. A transaction (transaction) is issued to execute the acquire actions defined in the rate model. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token Gs2Exchange:SkipByUserId Skip Exchange Await by specifying a user ID Accelerates or skips the waiting time of an exchange await. Supports four skip types: ‘complete’ skips the entire remaining wait, ‘minutes’ adds the specified minutes to skip seconds, ’totalRate’ skips a percentage of the total lock time, and ‘remainRate’ skips a percentage of the remaining wait time. The skip seconds are capped at the total lock time and cannot exceed it. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. awaitName string  UUID ~ 36 chars Exchange Await name Maintains a unique name for each Exchange Await. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each Exchange Await. skipType string (enum) enum {   “complete”,   “minutes”,   “totalRate”,   “remainRate” } “complete” Skip type Definition Description “complete” Complete skip “minutes” Skip by specifying time(minutes) “totalRate” Skip by specifying the percentage of total waiting time “remainRate” Skip by specifying the percentage of remaining waiting time minutes int {skipType} == “minutes” 0 ~ 2147483646 Minutes to skip * Enabled only if skipType is “minutes” rate float {skipType} == “totalRate” or {skipType} == “remainRate” 0 ~ 1 Percentage of time to skip timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Exchange Transaction Actions","url":"/api_reference/exchange/stamp_sheet/"},{"content":"Verify Action Gs2Experience:VerifyRankByUserId Verify rank by specifying a user ID Verifies that the specified user’s current rank satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank is less than the specified value “lessEqual” Rank is less than or equal to the specified value “greater” Rank is greater than the specified value “greaterEqual” Rank is greater than or equal to the specified value “equal” Rank is equal to the specified value “notEqual” Rank is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankValue long 0 0 ~ 9223372036854775805 Current Rank The rank (level) derived from the cumulative experience value using the rank threshold table. Starts at 0 and increases as experience thresholds are crossed. Cannot exceed the current rank cap value. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:VerifyRankCapByUserId Verify rank cap by specifying a user ID Verifies that the specified user’s current rank cap (including buff effects) satisfies a condition against a specified value. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Returns an error (BadRequest) if the verification condition is not met. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Rank cap is less than the specified value “lessEqual” Rank cap is less than or equal to the specified value “greater” Rank cap is greater than the specified value “greaterEqual” Rank cap is greater than or equal to the specified value “equal” Rank cap is equal to the specified value “notEqual” Rank cap is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Experience:SubExperienceByUserId Subtract experience by specifying a user ID Subtracts experience points from the specified user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Lost Experience timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:SubRankCapByUserId Subtract rank cap by specifying a user ID Decreases the rank cap of the specified user’s status. The rank cap will not go below 0. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Experience:AddExperienceByUserId Add experience by specifying a user ID Adds experience points to the specified user’s status. Rank is automatically recalculated based on the rank-up threshold values. When truncateExperienceWhenRankUp is true, excess experience beyond the rank-up threshold is discarded on rank up; when false (default), it carries over to the next rank. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Gained Experience truncateExperienceWhenRankUp bool? false Whether to truncate the remaining experience when ranking up timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:SetExperienceByUserId Set experience by specifying a user ID Directly sets the experience value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. Rank is automatically recalculated based on the rank-up threshold values. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. experienceValue long 0 0 ~ 9223372036854775805 Cumulative experience gained The total experience value accumulated by this status. The current rank is derived from this value using the rank threshold table. Experience cannot be gained beyond the threshold corresponding to the current rank cap. timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:AddRankCapByUserId Add rank cap by specifying a user ID Increases the rank cap of the specified user’s status. The rank cap cannot exceed the maxRankCap defined in the Experience Model. The rank cap determines the maximum rank a user can achieve for the specified property. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:SetRankCapByUserId Set rank cap by specifying a user ID Directly sets the rank cap value for the specified user’s status to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated status. The rank cap is capped at the maxRankCap defined in the Experience Model. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. timeOffsetToken string ~ 1024 chars Time offset token Gs2Experience:MultiplyAcquireActionsByUserId Multiply resources according to the rank of the property subject to the experience value by specifying user ID Looks up the acquire action rate for the specified rateName based on the property’s current rank value, multiplies the specified acquire actions by that rate (combined with baseRate), and starts a transaction to execute the resulting actions. This is used for rank-based reward scaling, where higher ranks earn proportionally more resources. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. experienceName string  ~ 128 chars Experience Model name The name of the experience model that defines the ranking rules for this status. Determines which rank threshold table and rank cap settings are applied. propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this status within the user’s scope. It is recommended to use a value that appends an experience model suffix to the GS2-Inventory Item Set GRN or GS2-Dictionary Entry GRN that possesses the experience. rateName string  ~ 128 chars Reward addition table name A unique identifier for this reward addition table. Referenced when specifying which multiplier table to apply to a particular acquire action. acquireActions List [] 0 ~ 100 items List of Acquire Actions baseRate float 1 0 ~ 1000000 Base rate timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Experience Transaction Actions","url":"/api_reference/experience/stamp_sheet/"},{"content":"Consume Action Gs2Formation:SubMoldCapacityByUserId Subtract capacity size by specifying a user ID Decreases the capacity of the form storage area (mold) for the specified user. The capacity will not go below 0. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Formation:AddMoldCapacityByUserId Add capacity size by specifying a user ID Increases the capacity of the form storage area (mold) for the specified user. The capacity cannot exceed the maxCapacity defined in the Mold Model. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Gs2Formation:SetMoldCapacityByUserId Set capacity size with specified user ID Directly sets the capacity of the form storage area (mold) for the specified user to an exact value. Captures and returns the state before the update as ‘old’, in addition to the updated mold. The capacity is capped at the maxCapacity defined in the Mold Model. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. moldModelName string  ~ 128 chars Form Storage Area Model name Form Storage Area Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. timeOffsetToken string ~ 1024 chars Time offset token Gs2Formation:AcquireActionsToFormProperties Apply acquire action to Form Properties by specifying a user ID Applies an acquire action to the form’s slot properties and starts a transaction to execute it. This is used to grant items or resources to the slots of a form, with optional config parameters for customization. Returns a transaction for transaction processing. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. acquireAction AcquireAction  Get action to be applied to form properties config List [] 0 ~ 1000 items List of Acquisition config timeOffsetToken string ~ 1024 chars Time offset token Gs2Formation:SetFormByUserId Set form by specifying a user ID Updates the slot values of a form for the specified user. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. moldModelName string  ~ 128 chars Form Storage Area Model name index int  0 ~ 2147483646 Index of form The zero-based index identifying which save slot this form occupies within the mold. The maximum index is limited by the mold’s current capacity. For example, index 0 might be “Party 1” and index 1 might be “Party 2”. slots List  1 ~ 10 items List of Slots timeOffsetToken string ~ 1024 chars Time offset token Gs2Formation:AcquireActionsToPropertyFormProperties Apply acquire action to property form properties Applies an acquire action to the properties of a property form, initiating a transaction. This is used to grant items or resources that are then set as slot values in the property form. The acquire action is executed as a transaction, and the resulting items are applied to the form’s slot properties. Configuration values can be passed to customize the acquire action behavior. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. propertyFormModelName string  ~ 128 chars Property Form Model name propertyId string  ~ 1024 chars Property ID A developer-defined identifier that uniquely identifies this property form instance. Typically set to the GRN of the owned resource (e.g., a GS2-Inventory item set) that this form configures, such as setting skills on a specific piece of equipment. acquireAction AcquireAction  Get action to be applied to form properties config List [] 0 ~ 1000 items List of Acquisition config timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Formation Transaction Actions","url":"/api_reference/formation/stamp_sheet/"},{"content":"Acquire Action Gs2Friend:UpdateProfileByUserId Update profile by specifying a user ID Updates the specified user’s profile with three distinct visibility levels (server-side operation): publicProfile: visible to all users followerProfile: visible only to followers friendProfile: visible only to friends Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. publicProfile string ~ 1024 chars Public profile Profile information visible to all players regardless of relationship. Typically used for display names, avatars, or other publicly shareable information. followerProfile string ~ 1024 chars Profile for followers Profile information visible only to players who follow this user. Can contain more detailed information than the public profile, such as gameplay statistics or status messages. friendProfile string ~ 1024 chars Profile for friends Profile information visible only to players who have an established mutual friend relationship. The most private profile level, suitable for sharing personal information like contact details or private messages. timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Friend Transaction Actions","url":"/api_reference/friend/stamp_sheet/"},{"content":"Verify Action Gs2Grade:VerifyGradeByUserId Verify grade by specifying a user ID Verifies that the specified user’s grade value satisfies a specified condition (server-side operation). Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. If the condition is not met, an error is returned with a descriptive message including the expected and actual values. When multiplyValueSpecifyingQuantity is true, the verification threshold value is multiplied by the specified quantity. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Grade is less than the specified value “lessEqual” Grade is less than or equal to the specified value “greater” Grade is greater than the specified value “greaterEqual” Grade is greater than or equal to the specified value “equal” Grade is equal to the specified value “notEqual” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 1 1 ~ 9223372036854775805 Current Grade The current grade value of this status. Used as an index into the grade model’s grade entries array to determine the rank cap for the linked GS2-Experience model. When this value changes, the rank cap of the associated experience status is automatically updated to the value defined in the corresponding grade entry. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Grade:VerifyGradeUpMaterialByUserId Verify grade up material by specifying a user ID Verifies whether a material property ID is valid for grading up the specified property for the specified user (server-side operation). The verification builds a regex pattern from the grade entry’s PropertyIdRegex and GradeUpPropertyIdRegex, then checks if the material property ID matches. Supports two verification types: ‘match’ (material must match the pattern) and ’notMatch’ (material must not match the pattern). Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. verifyType string (enum) enum {   “match”,   “notMatch” }  Type of verification Definition Description “match” Grade is equal to the specified value “notMatch” Grade is not equal to the specified value propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. materialPropertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Grade:SubGradeByUserId Subtract grade by specifying a user ID Subtracts the specified grade value from the specified user’s current grade for the given grade model and property (server-side operation). After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 0 0 ~ 9223372036854775805 Lost Grade timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Grade:AddGradeByUserId Add grade by specifying a user ID Adds the specified grade value to the user’s current grade for the given grade model and property. After updating the grade value, the rank cap is automatically applied to the linked GS2-Experience status. The rank cap value is determined by the grade entry matching the new grade level. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. gradeValue long 0 0 ~ 9223372036854775805 Gained Grade timeOffsetToken string ~ 1024 chars Time offset token Gs2Grade:ApplyRankCapByUserId Apply rank cap to GS2-Experience Status by specifying a user ID Applies the rank cap corresponding to the current grade to the linked GS2-Experience status for the specified user (server-side operation). Looks up the grade entry matching the current grade value to determine the rank cap value. This is useful when the grade has been modified externally and the Experience rank cap needs to be synchronized. Returns the updated grade status along with the Experience namespace name and the updated Experience status. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. timeOffsetToken string ~ 1024 chars Time offset token Gs2Grade:MultiplyAcquireActionsByUserId Multiply acquire actions by grade-based rate Multiplies the quantities of the specified acquire actions by a rate multiplier determined by the user’s current grade. The rate multiplier is looked up from the grade model’s acquireActionRates using the specified rateName and the current grade value. The multiplied acquire actions are then executed as a transaction, enabling grade-based reward scaling (e.g., higher grades receive more resources). Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeName string  ~ 128 chars Grade Model Name The name of the grade model that this status belongs to. References the grade model definition which contains the grade entry mappings, linked experience model, and reward addition tables. propertyId string  ~ 1024 chars Property ID A developer-defined identifier for this grade status, unique within the user and grade model. It is strongly recommended to use the same value as the property ID of the linked GS2-Experience status, as this ensures correct synchronization of grade values with rank caps. rateName string  ~ 128 chars Reward Addition Table Name A unique identifier for this multiplier table within the grade model. Referenced when applying grade-based reward scaling to specific acquire actions in transactions. acquireActions List [] 0 ~ 100 items List of Acquire Actions timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Grade Transaction Actions","url":"/api_reference/grade/stamp_sheet/"},{"content":"Verify Action Gs2Guild:VerifyCurrentMaximumMemberCountByGuildName Verify the maximum number of guild members by specifying a Guild name Verifies the specified guild’s currentMaximumMemberCount against the specified value using the chosen comparison operator (server-side operation). Supported operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Supports quantity specification: NO  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  ~ 128 chars Guild name verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” The maximum number of guild members is less than the specified value “lessEqual” The maximum number of guild members is less than or equal to the specified value “greater” The maximum number of guild members is greater than the specified value “greaterEqual” The maximum number of guild members is greater than or equal to the specified value “equal” The maximum number of guild members is equal to the specified value “notEqual” The maximum number of guild members is not equal to the specified value value int 1 ~ 2147483646 Maximum number of guild members multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity Gs2Guild:VerifyIncludeMemberByUserId Verify if guild members include user ID by specifying a user ID Verifies whether the specified user is or is not a member of the guild (server-side operation). Supports two verification types: ‘include’ and ’notInclude’. Supports quantity specification: NO  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. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Guild members include the specified user “notInclude” Guild members do not include the specified user timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Guild:DecreaseMaximumCurrentMaximumMemberCountByGuildName Decrease the maximum number of members by specifying a Guild name Decreases the specified guild’s currentMaximumMemberCount by the specified value (server-side operation). The resulting value cannot go below zero. Supports quantity specification: YES Whether the action is reversible: YES  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  ~ 128 chars Guild name value int 1 ~ 2147483646 Increase the maximum number of members Acquire Action Gs2Guild:IncreaseMaximumCurrentMaximumMemberCountByGuildName Add the maximum number of members by specifying a Guild name Increases the guild’s currentMaximumMemberCount by the specified value. The resulting value must not exceed the maximumMemberCount defined in the guild model. Supports quantity specification: YES Whether the action is reversible: YES  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  ~ 128 chars Guild name value int 1 ~ 2147483646 Increase the maximum number of members Gs2Guild:SetMaximumCurrentMaximumMemberCountByGuildName Set the maximum number of guild members by specifying a Guild name Sets the guild’s currentMaximumMemberCount to the specified absolute value. Unlike increase/decrease operations, this directly sets the value rather than applying a delta. Returns both the updated guild and the guild state before the update, allowing the caller to track the change. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). guildName string  ~ 128 chars Guild name guildModelName string  ~ 128 chars Guild Model name Guild Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). value int 1 ~ 2147483646 Set the maximum number of members","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Guild Transaction Actions","url":"/api_reference/guild/stamp_sheet/"},{"content":"Consume Action Gs2Idle:DecreaseMaximumIdleMinutesByUserId Decrease the maximum idle time by specifying a user ID Subtracts the specified number of minutes from the user’s maximum idle time for the given category. The maximum idle time cannot go below zero. If no status exists yet, it is automatically created before applying the decrease. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. decreaseMinutes int 1 ~ 2147483646 Minutes to decrease the maximum idle time timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Idle:IncreaseMaximumIdleMinutesByUserId Increase the maximum idle time by specifying a user ID Adds the specified number of minutes to the user’s maximum idle time for the given category. The maximum idle time determines the cap on how long idle rewards can accumulate. If no status exists yet, it is automatically created before applying the increase. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. increaseMinutes int 1 ~ 2147483646 Minutes to increase the maximum idle time timeOffsetToken string ~ 1024 chars Time offset token Gs2Idle:SetMaximumIdleMinutesByUserId Set the maximum idle time by specifying a user ID Sets the user’s maximum idle time for the given category to the specified absolute value. Unlike increase/decrease operations, this directly replaces the current maximum idle time. Returns both the updated status and the status before the update, allowing the caller to see what changed. If no status exists yet, it is automatically created before applying the value. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. maximumIdleMinutes int 1 ~ 2147483646 Maximum idle time to set timeOffsetToken string ~ 1024 chars Time offset token Gs2Idle:ReceiveByUserId Receive rewards by specifying a user ID Receives idle rewards for the specified user and category based on the accumulated idle time. The reward amount is calculated from the elapsed idle time divided by rewardIntervalMinutes, capped by maximumIdleMinutes. If a receiveScript is configured, it is executed before granting rewards and can modify or reject the receive operation. An overrideAcquireActionsScriptId can also modify the acquire actions (e.g., applying rate modifiers). After receiving, the idle timer is reset to the current time. Returns a transaction containing the acquire actions for the calculated rewards. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. categoryName string  ~ 128 chars Category Model Name The name of the category model that this status belongs to. References the category model definition which contains the reward interval, maximum idle time, acquire actions, and schedule settings used for idle reward calculation. config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Idle Transaction Actions","url":"/api_reference/idle/stamp_sheet/"},{"content":"Consume Action Gs2Inbox:OpenMessageByUserId Marking messages as opened by specifying a user ID Marks the specified message as read (opened) in the specified user’s inbox. This is a simple state transition that sets isRead to true without executing any acquire actions. To mark as read and also execute associated rewards, use the Read API instead. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Gs2Inbox:DeleteMessageByUserId Delete message by specifying a user ID Permanently removes a message from the specified user’s inbox. The message record is deleted regardless of its read status. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. messageName string  UUID ~ 36 chars Message Name Maintains a unique name for each message. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each message. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Inbox:SendMessageByUserId Send a message by specifying a user ID Creates and delivers a new message to the specified user’s inbox. The message can include metadata (arbitrary JSON content) and readAcquireActions (rewards granted when the message is read). Message expiration can be set using either an absolute timestamp (expiresAt) or a relative duration (expiresTimeSpan) from the time of delivery. If expiresAt is specified, it takes priority over expiresTimeSpan. The message starts in an unread state (isRead=false). Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. metadata string  ~ 4096 chars Metadata Arbitrary data representing the message content, such as a JSON string containing the message title, body text, sender information, and display parameters. GS2 does not interpret this value; it is passed through to the game client for rendering the message UI. Maximum 4096 characters. readAcquireActions List [] 0 ~ 100 items Acquire Actions on Open The list of acquire actions executed when the user opens this message. Used to attach rewards such as items, currency, or resources to messages. Multiple actions can be combined to grant different reward types simultaneously. Up to 100 actions per message. expiresAt long Expiration datetime Unix time, milliseconds expiresTimeSpan TimeSpan The period from the time a message was received (reference time) until it was deleted timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Inbox Transaction Actions","url":"/api_reference/inbox/stamp_sheet/"},{"content":"Verify Action Gs2Inventory:VerifyInventoryCurrentMaxCapacityByUserId Verify current max inventory capacity by specifying a user ID Verifies that the specified user’s current maximum inventory capacity satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. The verification uses the buffed capacity value (reflecting any active buff effects from GS2-Buff). Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Current max inventory capacity is less than the specified value “lessEqual” Current max inventory capacity is less than or equal to the specified value “greater” Current max inventory capacity is greater than the specified value “greaterEqual” Current max inventory capacity is greater than or equal to the specified value “equal” Current max inventory capacity is equal to the specified value “notEqual” Current max inventory capacity is not equal to the specified value currentInventoryMaxCapacity int  0 ~ 2147483646 Current max inventory capacity multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:VerifyItemSetByUserId Verify the quantity of Item Sets in possession by specifying the user ID Verifies that the specified user’s total item count satisfies the given condition. The count is summed across all item sets of the specified item type. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value itemSetName string ~ 36 chars Name identifying the item set count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:VerifyReferenceOfByUserId Verify the reference source by specifying the user ID Verifies the state of a reference on an item set for the specified user. Supports four verification types: not_entry (reference not yet registered), already_entry (reference already registered), empty (no references at all), and not_empty (at least one reference exists). If the condition is not met, an error is returned. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. verifyType string (enum) enum {   “not_entry”,   “already_entry”,   “empty”,   “not_empty” }  Type of verification Definition Description “not_entry” That the specified reference is not yet registered. “already_entry” That the specified reference is already registered. “empty” The number of elements registered as references is zero. “not_empty” At least one element registered as a reference source timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:VerifySimpleItemByUserId Verify the quantity of possessions in simple items by specifying a user ID Verifies that the specified user’s simple item count satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Simple Item Model Name The name of the simple item model that defines the type of item stored in this record. Used to identify which item definition this possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count long  0 ~ 9223372036854775805 Quantity in possession multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:VerifyBigItemByUserId Verify possession quantity of Big Items by specifying a user ID Verifies that the specified user’s big item count satisfies the specified condition. Supports six comparison operators: less, lessEqual, greater, greaterEqual, equal, and notEqual. The comparison is performed using arbitrary-precision arithmetic on string-based counts. If the condition is not met, an error is returned; if met, the request succeeds. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Big Item Model Name The name of the big item model that defines the type of item stored in this record. Used to identify which item definition this big item possession corresponds to. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count string  ~ 1024 chars Quantity in possession Integer value strings up to 1024 digits multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Inventory:ConsumeItemSetByUserId Consume Item Sets by specifying the user ID Reduces the quantity of the specified item in the given user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. consumeCount long  1 ~ 9223372036854775805 Consumption quantity itemSetName string ~ 36 chars Name identifying the Item Set timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:ConsumeSimpleItemsByUserId Consume Simple Items by specifying a user ID Reduces the quantity of items in the specified user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:ConsumeBigItemByUserId Consume Big Items by specifying a user ID Subtracts the specified quantity from the specified user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Inventory:AddCapacityByUserId Add inventory capacity size by specifying a user ID Incrementally increases the user’s inventory capacity by the specified amount. The resulting capacity cannot exceed the inventory model’s maxCapacity. If the inventory does not yet exist, it is automatically created with initialCapacity before adding the specified value. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. addCapacityValue int  1 ~ 2147483646 Capacity size to be added timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:SetCapacityByUserId Set inventory capacity size by specifying a user ID Sets the user’s inventory capacity to the specified absolute value. Returns both the inventory state before and after the update, allowing you to compare old and new capacity values. The new capacity value cannot exceed the inventory model’s maxCapacity. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that defines the structure and capacity settings for this inventory. Links the user’s inventory instance to its model definition, determining available item types and capacity limits. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. newCapacityValue int  1 ~ 2147483646 New maximum capacity for inventory timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:AcquireItemSetByUserId Acquire Item Sets by specifying the user ID Adds items to the user’s inventory. If an existing item set has room (below the stacking limit), items are added to it; otherwise, a new item set is created if multiple stacks are allowed. An optional expiresAt can set an expiration time for newly created item sets. Items with an expiration time already in the past are treated as empty. When createNewItemSet is true, a new item set is always created even if existing sets have room. If the total quantity exceeds the inventory capacity, the overflow count is returned, and overflow items may be forwarded to GS2-Inbox depending on the namespace configuration. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. acquireCount long  1 ~ 9223372036854775805 Acquisition quantity expiresAt long 0 Expiration time Unix time, milliseconds createNewItemSet bool false Even if there is room in an existing Item Set, you can create a new Item Set itemSetName string ~ 36 chars Name identifying the Item Set timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:AcquireItemSetWithGradeByUserId Acquire one Item Set while setting the grade to GS2-Grade by specifying the user ID Acquires exactly one item and simultaneously sets a grade value on it via GS2-Grade. This is used for items that have a quality/rank system where each individual item has a different grade value (e.g., equipment with varying stats). A new item set is always created (createNewItemSet behavior), and the grade is set through GS2-Grade’s SetGradeByUserId after the item acquisition. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model name Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. gradeModelId string  ~ 1024 chars Grade Model A unique resource name assigned to all information handled by GS2\" \u003e GRN gradeValue long  1 ~ 9223372036854775805 Grade value to set timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:AddReferenceOfByUserId Add a reference by specifying a user ID Registers a reference string on the specified item set for the specified user. References associate the item set with an external entity (e.g., an equipment slot or character). When protectReferencedItem is enabled on the inventory model, items with references cannot be consumed or deleted, preventing accidental loss of equipped items. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:DeleteReferenceOfByUserId Delete the reference source by specifying the user ID Removes a specific reference string from the specified item set for the specified user. After removal, if protectReferencedItem is enabled and no other references remain, the item becomes eligible for consumption or deletion again. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Inventory Model Name The name of the inventory model that contains this item set. Used together with itemName to identify which inventory and item type this possession belongs to. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Item Model Name The name of the item model that defines the type of item stored in this set. Combined with inventoryName, it determines the stacking limit and multi-stack behavior for this item set. itemSetName string  UUID ~ 36 chars Name identifying the Item Set Maintains a unique name for each item set. Names are automatically generated in UUID (Universally Unique Identifier) format and used to identify each item set. referenceOf string  ~ 1024 chars Reference A string identifier representing an external reference to this item set, such as an equipment slot or formation binding. When protectReferencedItem is enabled on the inventory model, item sets with references cannot be consumed or deleted. timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:AcquireSimpleItemsByUserId Acquire Simple Items by specifying a user ID Adds items to the user’s simple inventory using a batch of acquire counts. Multiple items can be acquired in a single atomic operation — the acquireCounts array specifies the item name and quantity for each item to acquire. Unlike regular item sets, simple items have no capacity limits, stacking limits, or expiration. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. acquireCounts List  1 ~ 100 items List of acquisition quantities for Simple Items timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:SetSimpleItemsByUserId Set the quantity of simple items by specifying a user ID Sets the absolute quantities of multiple simple items in a single atomic operation. The counts array specifies the item name and target quantity for each item. This overwrites the current quantities entirely, unlike acquire/consume which are relative operations. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Simple Inventory Model name Simple Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. counts List  1 ~ 100 items List of quantity of Simple Items in possession timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:AcquireBigItemByUserId Acquire Big Item by specifying a user ID Adds the specified quantity to the user’s big item count using arbitrary-precision arithmetic. The acquireCount must be a valid integer string up to 1024 digits; an invalid format will result in an error. If the item does not yet exist, it will be automatically created. A GS2-Script can be configured to execute custom logic when big items are acquired via the namespace settings. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). acquireCount string  ~ 1024 chars Acquisition quantity for a Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token Gs2Inventory:SetBigItemByUserId Set the Big Item by specifying a user ID Sets the big item count to the specified absolute value, replacing the current count entirely. The count must be a valid integer string up to 1024 digits. If the item does not yet exist, it will be automatically created. Unlike acquire/consume which perform relative operations, this sets the exact value directly. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). inventoryName string  ~ 128 chars Big Inventory Model name Big Inventory Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. itemName string  ~ 128 chars Big Item Model name Big Item Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). count string  ~ 1024 chars Quantity of Big Item Integer value strings up to 1024 digits timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Inventory Transaction Actions","url":"/api_reference/inventory/stamp_sheet/"},{"content":"Consume Action Gs2JobQueue:DeleteJobByUserId Delete a job by specifying a user ID Deletes a specific job from the specified user’s job queue. The job is removed regardless of its execution state. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. jobName string  UUID ~ 36 chars Job Name Maintains a unique name for each job. The name is automatically generated in UUID (Universally Unique Identifier) format and used to identify each job. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2JobQueue:PushByUserId Register jobs by specifying a user ID Registers one or more jobs to the user’s job queue (up to 10 at a time). Each job specifies a GS2-Script to execute, its arguments, and a maximum retry count. If enableAutoRun is enabled on the namespace, jobs are executed immediately and asynchronously after registration, and the autoRun flag in the response is set to true. If enableAutoRun is disabled, jobs are queued and must be executed manually via the Run API, with the autoRun flag set to false. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. jobs List 0 ~ 10 items List of jobs to add timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-JobQueue Transaction Actions","url":"/api_reference/job_queue/stamp_sheet/"},{"content":"Verify Action Gs2Limit:VerifyCounterByUserId Verify Counter value by specifying a user ID Verifies that the specified user’s counter value satisfies the given condition. Supports 6 comparison operators: less, lessEqual, greater, greaterEqual, equal, notEqual. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Possession quantity is less than the specified value “lessEqual” Possession quantity is less than or equal to the specified value “greater” Possession quantity is greater than the specified value “greaterEqual” Possession quantity is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value count int 0 0 ~ 2147483646 Count Value The current usage count for this counter. Incremented by the countUp operation and compared against the maximum value specified at that time. Automatically reset to zero when the limit model’s reset timing is reached. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Limit:CountUpByUserId Count-up by specifying a user ID Increments the specified user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. countUpValue int 1 1 ~ 2147483646 Amount to count up maxValue int 1 ~ 2147483646 Maximum value allowed to count up timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Limit:CountDownByUserId Count-down by specifying a user ID Decrements the specified user’s counter by the specified count-down value. The counter value will not go below 0. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. countDownValue int 1 1 ~ 2147483646 Amount to count down timeOffsetToken string ~ 1024 chars Time offset token Gs2Limit:DeleteCounterByUserId Delete Counter by specifying a user ID Deletes the specified user’s counter, resetting the usage count. This effectively removes the limit restriction for this counter, allowing the user to start counting from 0 again. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). limitName string  ~ 128 chars Usage Limit Model Name The name of the limit model that this counter belongs to. Determines the reset schedule (daily, weekly, monthly, etc.) applied to this counter’s value. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. counterName string  ~ 128 chars Counter Name A unique identifier for this counter within the limit model. Multiple counters can share the same limit model with different names, allowing separate usage tracking (e.g., one counter per quest or per product) without creating separate limit models. timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Limit Transaction Actions","url":"/api_reference/limit/stamp_sheet/"},{"content":"Consume Action Gs2LoginReward:MarkReceivedByUserId Mark as received by specifying a user ID Manually marks a specific step as received for the specified user’s bonus model. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. stepNumber int  0 ~ 100 Step Number timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2LoginReward:DeleteReceiveStatusByUserId Delete Receive Status by specifying a user ID Deletes all receive status data for the specified user’s bonus model, completely resetting the bonus progress. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token Gs2LoginReward:UnmarkReceivedByUserId Unmark as received by specifying a user ID Reverses a previously marked step back to unreceived for the specified user’s bonus model. If the specified step was not marked as received, an error is returned. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). bonusModelName string  ~ 128 chars Bonus Model Name The name of the Login Bonus Model that this receive status is associated with. Links the user’s receive progress to a specific bonus model definition, determining which reward list and distribution rules apply. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. stepNumber int  0 ~ 100 Step Number timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-LoginReward Transaction Actions","url":"/api_reference/login_reward/stamp_sheet/"},{"content":"Acquire Action Gs2Lottery:DrawByUserId Execute a lottery by specifying a User ID Performs a lottery draw for the specified user based on the lottery model configuration. The lottery supports two methods: Prize Table mode (using predefined probability tables) and Script mode (using a GS2-Script to determine prizes). In box lottery mode, drawn prizes are removed from the box and cannot be drawn again. If the box is empty, an Empty error is returned. The drawn prizes are issued as a transaction. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name lotteryName string  ~ 128 chars Lottery Model name Lottery Model-specific name. Specified using alphanumeric characters, hyphen (-), underscore (_), and period (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. count int  1 ~ 1000 Number of draws config List [] 0 ~ 1000 items Configuration values applied to transaction placeholders timeOffsetToken string ~ 1024 chars Time offset token Gs2Lottery:ResetBoxByUserId Reset box with specified user ID Resets the specified user’s box to its initial state, returning all drawn prizes back into the box. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). prizeTableName string  ~ 128 chars Prize Table name userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Lottery Transaction Actions","url":"/api_reference/lottery/stamp_sheet/"},{"content":"Verify Action Gs2Matchmaking:VerifyIncludeParticipantByUserId Verify if persistent gathering includes user ID by specifying a user ID Verifies whether the specified user is or is not a participant of the season gathering. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). seasonName string  ~ 128 chars Season Model name Season Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). season long  0 ~ 9223372036854775805 Season tier long  0 ~ 9223372036854775805 Tier The tier level used to group players of similar rank together. Determined by the player’s rank in the GS2-Experience model specified in the SeasonModel. Players are only matched with others in the same tier, ensuring fair competition. seasonGatheringName string  UUID ~ 128 chars Season Gathering Name Season Gathering-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. verifyType string (enum) enum {   “include”,   “notInclude” }  Type of verification Definition Description “include” Specified user is included in the Season Gathering “notInclude” Specified user is not included in the Season Gathering timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Matchmaking Transaction Actions","url":"/api_reference/matchmaking/stamp_sheet/"},{"content":"Verify Action Gs2Mission:VerifyCompleteByUserId Verify Completion Status by specifying a user ID Verifies the completion or receipt status of a mission task for the specified user. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. verifyType string (enum) enum {   “completed”,   “notCompleted”,   “received”,   “notReceived”,   “completedAndNotReceived” }  Type of verification Definition Description “completed” Condition is achieved “notCompleted” Condition is not achieved “received” Reward has been received “notReceived” Reward has not been received “completedAndNotReceived” Condition is achieved and reward has not been received missionTaskName string  ~ 128 chars Mission Task Model name Mission Task Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:VerifyCounterValueByUserId Verify counter value by specifying a user ID Verifies that a counter’s scoped value meets the specified condition for the specified user. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Counter value is less than the specified value “lessEqual” Counter value is less than or equal to the specified value “greater” Counter value is greater than the specified value “greaterEqual” Counter value is greater than or equal to the specified value “equal” Counter value is equal to the specified value “notEqual” Counter value is not equal to the specified value scopeType string (enum) enum {   “resetTiming”,   “verifyAction” } “resetTiming” Scope type Indicates whether this scoped value is based on a reset timing schedule or a verify action condition. Definition Description “resetTiming” Reset timing “verifyAction” Verify Action resetType string (enum) enum {   “notReset”,   “daily”,   “weekly”,   “monthly”,   “days” } {scopeType} == “resetTiming”  Reset timing The reset timing for this scoped value. Determines the period over which the counter value is accumulated before being reset. Only applicable when scopeType is “resetTiming”. Definition Description “notReset” Not Reset “daily” Daily “weekly” Weekly “monthly” Monthly “days” Every fixed number of days * Required if scopeType is “resetTiming” conditionName string {scopeType} == “verifyAction”  ~ 128 chars Condition Name The name of the verify action condition that this scoped value corresponds to. Used to identify which condition scope this value belongs to. Only applicable when scopeType is “verifyAction”. * Required if scopeType is “verifyAction” value long 0 0 ~ 9223372036854775805 Count value The accumulated counter value for this scope. Increases when the counter is incremented and decreases when decremented. The value is capped at the maximum and will not go below zero. multiplyValueSpecifyingQuantity bool false Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Mission:ReceiveByUserId Receive rewards for mission accomplishment Marks the specified mission task as received for the specified user. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:BatchReceiveByUserId Receive rewards for multiple mission tasks in bulk Marks multiple mission tasks as received at once within the same mission group. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. missionTaskNames List  1 ~ 100 items Task name list timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:DecreaseCounterByUserId Decrease counter by specifying a user ID Subtracts the specified value from the counter for the specified user. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. value long  1 ~ 9223372036854775805 Value to be subtracted timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:ResetCounterByUserId Reset counter by specifying a user ID Resets the counter values for the specified scopes for the specified user. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. scopes List  1 ~ 20 items List of scopes timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Mission:RevertReceiveByUserId Revert the status of mission accomplishment to unreceived Reverts the received status of a mission task back to unreceived. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). missionGroupName string  ~ 128 chars Mission Group Name The name of the mission group that this completion record belongs to. One Complete record exists per user per mission group. missionTaskName string  ~ 128 chars Task Name userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:IncreaseCounterByUserId Increase counter by specifying a user ID Adds the specified value to the counter for the specified user. After incrementing, all mission tasks referencing this counter are automatically re-evaluated, and any newly completed missions are returned in the changedCompletes response. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. value long  1 ~ 9223372036854775805 Value to be added timeOffsetToken string ~ 1024 chars Time offset token Gs2Mission:SetCounterByUserId Set counter by specifying a user ID Sets the counter scoped values directly for the specified user, replacing existing values. Returns both the old and new counter states, as well as any newly completed missions in the changedCompletes response. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). counterName string  ~ 128 chars Counter Model name The name of the Counter Model that this counter instance is based on. Links to the counter model definition that specifies the scopes and reset timings. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. values List 0 ~ 20 items List of values to be set timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Mission Transaction Actions","url":"/api_reference/mission/stamp_sheet/"},{"content":"Consume Action Gs2Money:WithdrawByUserId Consume balance from wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. count int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency timeOffsetToken string ~ 1024 chars Time offset token Gs2Money:RecordReceipt Record receipt Records and validates a purchase receipt from a store platform (Apple App Store / Google Play). The receipt is verified against the platform’s servers to prevent fraud. Duplicate receipts are rejected to prevent replay attacks. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. contentsId string  ~ 1024 chars Content IDs sold on the store platform receipt string  ~ 524288 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Money:DepositByUserId Deposit balance to wallet by specifying a user ID Adds the specified amount of currency to the wallet for the specified user. If the price is 0, it is treated as free currency; otherwise, it is treated as paid currency. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. slot int  0 ~ 100000000 Slot Number An identifier for separating wallet balances by platform or context. Different slots allow managing separate paid currency pools (e.g., iOS purchases in slot 0, Android in slot 1). Free currency can optionally be shared across all slots via the namespace’s shareFree setting. price float  0 ~ 100000.0 Purchase Price count int  1 ~ 2147483646 Quantity of premium currency to be granted timeOffsetToken string ~ 1024 chars Time offset token Gs2Money:RevertRecordReceipt Delete receipt record by specifying a user ID Reverts a previously recorded receipt by extracting the transaction ID and deleting the corresponding record. Used for handling refunds or chargebacks from the store platform. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. receipt string  ~ 524288 chars Receipt timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Money Transaction Actions","url":"/api_reference/money/stamp_sheet/"},{"content":"Consume Action Gs2Money2:WithdrawByUserId Withdraw balance from Wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed paidOnly bool false Whether to target only paid currency timeOffsetToken string ~ 1024 chars Time offset token Gs2Money2:VerifyReceiptByUserId Mark a receipt as used by specifying a user ID Verifies a purchase receipt for the specified user and records it as used. An event log is recorded and the verify receipt script configured in the namespace is executed. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. contentName string  ~ 128 chars Store Content Model name receipt Receipt  Receipt timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Money2:DepositByUserId Deposit balance to Wallet by specifying a user ID Adds the specified deposit transactions to the wallet for the specified user. An event log is recorded for each deposit transaction. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. slot int  0 ~ 100000000 Slot Number Identifies the wallet slot. Different slots can be used to manage currency separately per platform (e.g., one slot for iOS, another for Android) when cross-platform balance sharing is not allowed. depositTransactions List  1 ~ 1000 items List of Deposit transactions timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Money2 Transaction Actions","url":"/api_reference/money2/stamp_sheet/"},{"content":"Consume Action Gs2Quest:DeleteProgressByUserId Delete Quest Progress by specifying a user ID Deletes the current quest progress for the specified user. This cancels the quest in progress and allows starting a new quest. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Quest:CreateProgressByUserId Create a new Quest Progress by specifying a user ID Creates a quest progress by looking up the quest model, performing a lottery on the quest content, and starting the quest. If a quest is already in progress, it returns an error unless the force flag is set. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. questModelId string  ~ 1024 chars Quest Model A unique resource name assigned to all information handled by GS2\" \u003e GRN to Start force bool false If have a quest already started, you can discard it and start it config List [] 0 ~ 32 items Configuration values applied to transaction variables timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Quest Transaction Actions","url":"/api_reference/quest/stamp_sheet/"},{"content":"Verify Action Gs2Ranking2:VerifyGlobalRankingScoreByUserId Verify the score of the global ranking specifying User ID Verifies the global ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user. Must be within the range defined by the ranking model’s minimumValue and maximumValue settings. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Ranking2:VerifyClusterRankingScoreByUserId Verify the score of the cluster ranking specifying User ID Verifies the cluster ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster (guild, gathering, or arbitrary group) that this score belongs to. Verified against the cluster type setting to ensure the user is a member. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score The score value submitted by the user within this cluster. multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Ranking2:VerifySubscribeRankingScoreByUserId Verify the score of the subscribe ranking specifying User ID Verifies the subscribe ranking score of the specified user against a specified value using comparison operators (less, lessEqual, greater, greaterEqual, equal, notEqual). Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. rankingName string  ~ 128 chars Subscribe Ranking Model name Subscribe Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Score is less than the specified value “lessEqual” Score is less than or equal to the specified value “greater” Score is greater than the specified value “greaterEqual” Score is greater than or equal to the specified value “equal” Score is equal to the specified value “notEqual” Score is not equal to the specified value season long 0 ~ 9223372036854775805 Season score long  0 ~ 9223372036854775805 Score multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Ranking2:CreateGlobalRankingReceivedRewardByUserId Record global ranking reward receipt history specifying User ID Records a reward receipt history for the specified global ranking on behalf of the specified user. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Global Ranking Model name Global Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token Gs2Ranking2:CreateClusterRankingReceivedRewardByUserId Record Cluster Ranking Reward Received History by specifying a user ID Records a reward receipt history for the specified cluster ranking and cluster on behalf of the specified user. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). rankingName string  ~ 128 chars Cluster Ranking Model name Cluster Ranking Model-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). clusterName string  ~ 1024 chars Cluster Name The name of the cluster for which the ranking reward was received. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. season long 0 ~ 9223372036854775805 Season timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Ranking2 Transaction Actions","url":"/api_reference/ranking2/stamp_sheet/"},{"content":"Verify Action Gs2Schedule:VerifyTriggerByUserId Verify the elapsed time since the Trigger was pulled by specifying a user ID Verifies conditions related to the trigger’s state for the specified user. The verifyType can be: ’notTriggerd’, ’elapsed’, or ’notElapsed’. Returns an error if the verification condition is not met. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “notTriggerd”,   “elapsed”,   “notElapsed” }  Type of verification Definition Description “notTriggerd” Trigger not pulled “elapsed” Elapsed time “notElapsed” Not elapsed time elapsedMinutes int {verifyType} in [“elapsed”, “notElapsed”]  0 ~ 2147483646 Elapsed time (minutes) * Required if verifyType is “elapsed”,“notElapsed” timeOffsetToken string ~ 1024 chars Time offset token Gs2Schedule:VerifyEventByUserId Verify whether the Event is active by specifying a user ID Verifies whether the specified event is currently in its active schedule period for the specified user. The verifyType can be set to ‘inSchedule’ or ’notInSchedule’. Returns an error if the verification condition is not met. Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. eventName string  ~ 128 chars Event name Event-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). verifyType string (enum) enum {   “inSchedule”,   “notInSchedule” }  Type of verification Definition Description “inSchedule” The event is in its active period “notInSchedule” The event is not in its active period timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Schedule:DeleteTriggerByUserId Delete Trigger by specifying a user ID Deletes the specified trigger for the specified user. Deleting a trigger deactivates associated relative schedule events. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Schedule:TriggerByUserId Execute the Trigger by specifying a user ID Pulls a trigger for the specified user. The trigger strategy determines behavior: ‘renew’ resets with new TTL, ’extend’ extends existing TTL, ‘drop’ ignores if already pulled, ‘repeatCycleEnd’/‘repeatCycleNextStart’/‘absoluteEnd’ aligns expiration with the specified event’s schedule. Pulling a trigger activates associated relative schedule events. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. triggerStrategy string (enum) enum {   “renew”,   “extend”,   “drop”,   “repeatCycleEnd”,   “repeatCycleNextStart”,   “absoluteEnd” }  Trigger Execution Policy Definition Description “renew” Redraw with a new period if the trigger has already been pulled “extend” Extend the period if the trigger has already been pulled “drop” Ignore if the trigger has already been pulled “repeatCycleEnd” Trigger to expire at the end of the repeat period of the specified event “repeatCycleNextStart” Trigger to expire at the next repeat start date and time of the specified event “absoluteEnd” Trigger to expire at the end date and time of the specified event ttl int {triggerStrategy} in [“renew”, “extend”, “drop”]  0 ~ 2147483646 Trigger expiration time (seconds) * Required if triggerStrategy is “renew”,“extend”,“drop” eventId string {triggerStrategy} in [“repeatCycleEnd”, “repeatCycleNextStart”, “absoluteEnd”]  ~ 1024 chars Event A unique resource name assigned to all information handled by GS2\" \u003e GRN * Required if triggerStrategy is “repeatCycleEnd”,“repeatCycleNextStart”,“absoluteEnd” timeOffsetToken string ~ 1024 chars Time offset token Gs2Schedule:ExtendTriggerByUserId Extend the period of a trigger by specifying a user ID Extends the expiration period of an existing trigger for the specified user by the specified number of seconds. If the trigger does not exist, a new trigger is created with the specified extension period as its TTL. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). triggerName string  ~ 128 chars Trigger name Trigger-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. extendSeconds int  0 ~ 2147483646 Trigger extension period (seconds) timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Schedule Transaction Actions","url":"/api_reference/schedule/stamp_sheet/"},{"content":"Acquire Action Gs2Script:InvokeScript Execute the script Synchronously executes the specified Lua script with the provided JSON arguments. Returns the execution result including status code, return value, transaction information, random number state, execution time, and standard output. Supports transaction handling for atomic operations across GS2 services. Supports quantity specification: NO Whether the action is reversible: NO  scriptId string  ~ 1024 chars Script A unique resource name assigned to all information handled by GS2\" \u003e GRN userId string ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. args string “{}” ~ 5242880 chars Arguments (JSON Format) randomStatus RandomStatus Random number status timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Script Transaction Actions","url":"/api_reference/script/stamp_sheet/"},{"content":"Verify Action Gs2SerialKey:VerifyCodeByUserId Verify the validity of the Serial Code by specifying a user ID Verifies a serial code for the specified user without consuming it. Supports verification against a specific campaign model name, and can check whether the code is active (unused) or inactive (already used). Supports quantity specification: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. campaignModelName string ~ 128 chars Campaign name The name of the campaign model this serial code belongs to. Campaign information is embedded within the serial code itself, so only the namespace needs to be specified when using the code. verifyType string (enum) enum {   “active”,   “inactive” }  Verification type Definition Description “active” Active “inactive” Inactive timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2SerialKey:UseByUserId Using Serial Code by specifying a user ID Marks a serial code as used by the specified user. Validates that the code exists and has not already been used. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2SerialKey:RevertUseByUserId Serial Code set to unused by specifying a user ID Reverts a used serial code back to unused status. Validates that the code is currently in used state before reverting. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. code string  ~ 48 chars Serial Code The serial code string in the format “XXXXX-XXXX-XXXXX-XXXX-XXXX”. Each code is unique and includes campaign identification information. The code format and data length are fixed and cannot be changed. timeOffsetToken string ~ 1024 chars Time offset token Gs2SerialKey:IssueOnce Issue a serial code Issues a single serial code immediately. The code is generated using AES encryption and base32 encoding in the format XXXXX-XXXX-XXXXX-XXXX-XXXXX. Unlike batch issuance jobs, this generates and returns a code synchronously. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). campaignModelName string  ~ 128 chars Campaign Model name 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.","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-SerialKey Transaction Actions","url":"/api_reference/serial_key/stamp_sheet/"},{"content":"Consume Action Gs2Showcase:IncrementPurchaseCountByUserId Increment the number of times a Random Displayed Item has been purchased by specifying the user ID Increments the purchase count for a specific Random Displayed Item in the Random Showcase for the specified user. Used for tracking purchase limits per rotation period. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name displayItemName string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. count int  0 ~ 100 Number of purchase times to add timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Showcase:DecrementPurchaseCountByUserId Decrement the number of times a Random Displayed Item has been purchased by specifying the user ID Decrements the purchase count for a specific Random Displayed Item in the Random Showcase. Used to reverse purchases or adjust purchase counters. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name displayItemName string  ~ 128 chars Number of Random Displayed Item purchases name The name of the Random Displayed Item whose purchase count is being tracked. Corresponds to the Random Displayed Item name in the Random Showcase. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. count int  0 ~ 100 Number of purchase times to subtract timeOffsetToken string ~ 1024 chars Time offset token Gs2Showcase:ForceReDrawByUserId Re-draw the contents of the Random Showcase by specifying a user ID Forces a redraw of the random showcase items for the specified user, resetting the current selection and triggering a new random item selection from the configured pool. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). showcaseName string  ~ 128 chars Random Showcase Name userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Showcase Transaction Actions","url":"/api_reference/showcase/stamp_sheet/"},{"content":"Consume Action Gs2SkillTree:MarkRestrainByUserId Revert a node to unreleased state by specifying a user ID Validates that the specified nodes can be restrained (no dependent nodes must be in released state), then marks them as unreleased. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of node model names timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2SkillTree:MarkReleaseByUserId Mark a node as released by specifying a user ID Validates that the specified nodes can be released (prerequisite nodes must already be released), then marks them as released. Supports quantity specification: NO Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. propertyId string  ~ 1024 chars Property ID An identifier that allows multiple independent skill tree instances per user. Enables scenarios where a player has separate skill trees for different characters or contexts within the same namespace. Maximum 1024 characters. nodeModelNames List  1 ~ 1000 items List of Node Model names timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-SkillTree Transaction Actions","url":"/api_reference/skill_tree/stamp_sheet/"},{"content":"Verify Action Gs2Stamina:VerifyStaminaValueByUserId Verify the value of the current Stamina by specifying a user ID Validates that the current stamina value for the specified user meets the specified condition against the given threshold without modifying any state. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:VerifyStaminaMaxValueByUserId Verify the value of the max stamina by specifying a user ID Validates that the maximum stamina capacity (including buff modifications) for the specified user meets the specified condition against the given threshold without modifying any state. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:VerifyStaminaRecoverIntervalMinutesByUserId Verify the value of the recovery interval minutes by specifying a user ID Validates that the stamina recovery interval (minutes) for the specified user meets the specified condition against the given threshold without modifying any state. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:VerifyStaminaRecoverValueByUserId Verify the value of the recovery value by specifying a user ID Validates that the stamina recovery amount (including buff modifications) for the specified user meets the specified condition against the given threshold without modifying any state. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:VerifyStaminaOverflowValueByUserId Verify the value of the overflow value by specifying a user ID Validates that the stamina overflow amount for the specified user meets the specified condition against the given threshold without modifying any state. Supports quantity specification: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. verifyType string (enum) enum {   “less”,   “lessEqual”,   “greater”,   “greaterEqual”,   “equal”,   “notEqual” }  Type of verification Definition Description “less” Value is less than the specified value “lessEqual” Value is less than or equal to the specified value “greater” Value is greater than the specified value “greaterEqual” Value is greater than or equal to the specified value “equal” Possession quantity is equal to the specified value “notEqual” Possession quantity is not equal to the specified value value int  0 ~ 2147483646 Value to be verified multiplyValueSpecifyingQuantity bool true Whether to multiply the value used for verification when specifying the quantity timeOffsetToken string ~ 1024 chars Time offset token Consume Action Gs2Stamina:DecreaseMaxValueByUserId Subtract the maximum value of stamina by specifying the user ID Reduces the maximum stamina capacity by the specified amount for the given user. May be used to apply debuffs or penalties to stamina capacity. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. decreaseValue int  0 ~ 2147483646 Maximum amount of stamina to be decreased timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:ConsumeStaminaByUserId Consume Stamina by specifying a user ID Deducts the specified amount from the current stamina value for the given user. Returns an Insufficient error if the current stamina value is less than the consume amount. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. consumeValue int  1 ~ 2147483646 Amount of stamina consumed timeOffsetToken string ~ 1024 chars Time offset token Acquire Action Gs2Stamina:RecoverStaminaByUserId Recover Stamina by specifying a user ID Recovers stamina by the specified amount up to the maximum capacity. If the recovery causes the value to exceed the maximum and overflow mode is enabled, the excess is tracked as an overflow value. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. recoverValue int  1 ~ 2147483646 Amount of stamina recovery timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:RaiseMaxValueByUserId Add the maximum value of stamina by specifying the user ID Permanently increases the maximum stamina capacity by the specified amount. Used for permanent stat increases such as level-up rewards or item effects. Supports quantity specification: YES Whether the action is reversible: YES  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. raiseValue int  0 ~ 2147483646 Maximum amount of stamina to be increased timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:SetMaxValueByUserId Update the maximum value of stamina by specifying a user ID Sets the maximum stamina capacity to the specified value. The old stamina state is preserved in the response for audit purposes. Used for administrative overrides or special event adjustments. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:SetRecoverIntervalByUserId Update stamina recovery interval (minutes) by specifying a user ID Sets the stamina recovery interval to the specified value in minutes. The old stamina state is preserved in the response for audit purposes. Controls how frequently the stamina recovers automatically. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. recoverIntervalMinutes int  1 ~ 2147483646 Stamina recovery interval (minutes) timeOffsetToken string ~ 1024 chars Time offset token Gs2Stamina:SetRecoverValueByUserId Set the amount of stamina recovery by specifying the user ID Sets the stamina recovery amount to the specified value. The old stamina state is preserved in the response for audit purposes. Controls how much stamina is recovered per recovery interval. Supports quantity specification: YES Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). staminaName string  ~ 128 chars Stamina Model Name The name of the StaminaModel that defines the recovery parameters, capacity, and table references for this stamina instance. This links the per-user stamina state to its corresponding model definition. userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. recoverValue int  1 ~ 2147483646 Amount of stamina recovery timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-Stamina Transaction Actions","url":"/api_reference/stamina/stamp_sheet/"},{"content":"Acquire Action Gs2StateMachine:StartStateMachineByUserId Start state machine by specifying a user ID Starts a new state machine instance for the specified user using the latest master version. Arguments are passed as JSON and parsed into state machine variables. An optional TTL (in minutes) can be set; if omitted, the state machine remains valid for approximately 10 years. Supports quantity specification: NO Whether the action is reversible: NO  namespaceName string  ~ 128 chars Namespace name Namespace-specific name. Specified using alphanumeric characters, hyphens (-), underscores (_), and periods (.). userId string  ~ 128 chars User ID Specify #{userId} to substitute the currently logged-in user’s ID. args string “{}” ~ 4096 chars Arguments to be passed to the state machine ttl int 1 ~ 525600 Validity period (minutes) timeOffsetToken string ~ 1024 chars Time offset token","lang":"en","section":"api_reference","summary":"Specification of verify/consume/acquire transaction actions\n","title":"GS2-StateMachine Transaction Actions","url":"/api_reference/state_machine/stamp_sheet/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Exchange:RateModel Exchange Rate Model Target fields for buff application lockTime  lockTime int {timingType} == “await”  0 ~ 538214400 Waiting time (minutes) from the execution of the exchange until the reward is actually received Only applicable when timingType is await . Specifies the number of minutes that must elapse in real time after the exchange is initiated before the player can claim the rewards. The waiting time can be shortened by using the skip mechanism. * Required if timingType is “await” Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:RateModel Exchange Rate Model Example Master Data acquireActions  acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the exchange. Multiple acquire actions can be specified to grant various resource types simultaneously. These actions are executed as acquire actions within a distributed transaction. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:RateModel Exchange Rate Model Example Master Data verifyActions  verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks that must all pass before the exchange is executed. If any verify action fails, the exchange is aborted without consuming resources. Used to enforce conditions such as level requirements or inventory capacity. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:RateModel Exchange Rate Model Example Master Data consumeActions  consumeActions List [] 0 ~ 10 items List of Consume Actions Defines the resources (cost) that the player must pay to perform this exchange. Multiple consume actions can be specified, allowing complex exchange costs such as requiring both gold and items. These actions are executed as consume actions within a distributed transaction. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:RateModel Exchange Rate Model Example Master Data Gs2Exchange:IncrementalRateModel Incremental Cost Exchange Rate Model Target fields for buff application acquireActions  acquireActions List [] 0 ~ 100 items List of Acquire Actions Defines the resources (rewards) that the player receives upon completing the incremental exchange. The rewards remain constant regardless of the exchange count; only the cost increases with each exchange. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:IncrementalRateModel Incremental Cost Exchange Rate Model Example Master Data consumeAction  consumeAction ConsumeAction  Consume Action (Quantity and Value are overwritten automatically) Defines the type of resource consumed as cost for the exchange. The actual quantity is calculated dynamically based on the exchange count and the calculation type (linear, power, or script). Only the action type and target resource need to be specified; the quantity field is overwritten automatically. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:IncrementalRateModel Incremental Cost Exchange Rate Model Example Master Data maximumExchangeCount  maximumExchangeCount int 2147483646 0 ~ 2147483646 Maximum number of exchanges The maximum number of times this incremental exchange can be performed by a user. Once the exchange count reaches this limit, further exchanges are denied until the count is reset via GS2-Limit. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Exchange:Namespace Namespace Example Master Data Gs2Exchange:IncrementalRateModel Incremental Cost Exchange Rate Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Exchange Buff Reference","url":"/api_reference/exchange/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Experience:Status Status Target fields for buff application rankCapValue  rankCapValue long  0 ~ 9223372036854775805 Current Rank Cap The maximum rank this status can currently reach. Initially set to the experience model’s defaultRankCap, and can be raised up to maxRankCap through rank cap increase operations such as limit breaking. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Experience:ExperienceModel Experience Model Example Master Data Gs2Experience:Status Status Example Master Data Action Types of actions that can apply buffs Gs2Experience:AddExperienceByUserId Add experience by specifying a user ID Adds experience points to the specified user’s status. Rank is automatically recalculated based on the rank-up threshold values. When truncateExperienceWhenRankUp is true, excess experience beyond the rank-up threshold is discarded on rank up; when false (default), it carries over to the next rank. Target fields for buff application experienceValue Status - Status  experienceValue long 0 0 ~ 9223372036854775805 Gained Experience Example Master Data Buff Application Condition Model Gs2Experience:ExperienceModel Experience Model Example Master Data Gs2Experience:Status Status Example Master Data Gs2Experience:SubExperience Subtract experience Subtracts experience points from the requesting user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values. Target fields for buff application experienceValue Status - Status  experienceValue long 0 0 ~ 9223372036854775805 Lost Experience Example Master Data Buff Application Condition Model Gs2Experience:ExperienceModel Experience Model Example Master Data Gs2Experience:Status Status Example Master Data Gs2Experience:SubExperienceByUserId Subtract experience by specifying a user ID Subtracts experience points from the specified user’s status. Experience will not go below 0. Rank is automatically recalculated based on the rank-up threshold values. Target fields for buff application experienceValue Status - Status  experienceValue long 0 0 ~ 9223372036854775805 Lost Experience Example Master Data Buff Application Condition Model Gs2Experience:ExperienceModel Experience Model Example Master Data Gs2Experience:Status Status Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Experience Buff Reference","url":"/api_reference/experience/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Formation:Mold Form Storage Area Target fields for buff application capacity  capacity int  0 ~ 2147483646 Current Capacity The number of form save slots currently available to this player for this mold. Initially set to the mold model’s initialMaxCapacity and can be expanded up to maxCapacity through capacity increase operations. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Formation:MoldModel Form Storage Area Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Formation Buff Reference","url":"/api_reference/formation/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Idle:Status Status Target fields for buff application maximumIdleMinutes  maximumIdleMinutes int 0 0 ~ 2147483646 Maximum Idle Minutes The maximum idle time in minutes that this status can accumulate. Initialized from the category model’s defaultMaximumIdleMinutes when the status is created. Can be increased per-user via acquire actions, allowing premium users or event participants to accumulate more idle rewards. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Idle:CategoryModel Category Model Example Master Data Gs2Idle:CategoryModel Category Model Target fields for buff application acquireActions  acquireActions List [] 0 ~ 100 items List of Acquire Actions The collection of acquire actions that are executed together when this reward interval is triggered. Multiple actions can be combined to grant different types of rewards simultaneously for a single idle reward cycle. Up to 100 actions per list. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Idle:CategoryModel Category Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Idle Buff Reference","url":"/api_reference/idle/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Inventory:Inventory Inventory Target fields for buff application currentInventoryMaxCapacity  currentInventoryMaxCapacity int  1 ~ 2147483646 Maximum Capacity The current maximum number of inventory slots available to this user. Initialized from the inventory model’s initialCapacity and can be expanded up to the model’s maxCapacity through acquire actions or direct API calls. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Inventory:InventoryModel Inventory Model Example Master Data Action Types of actions that can apply buffs Gs2Inventory:AcquireItemSetByUserId Acquire Item Sets by specifying the user ID Adds items to the user’s inventory. If an existing item set has room (below the stacking limit), items are added to it; otherwise, a new item set is created if multiple stacks are allowed. An optional expiresAt can set an expiration time for newly created item sets. Items with an expiration time already in the past are treated as empty. When createNewItemSet is true, a new item set is always created even if existing sets have room. If the total quantity exceeds the inventory capacity, the overflow count is returned, and overflow items may be forwarded to GS2-Inbox depending on the namespace configuration. Target fields for buff application acquireCount ItemSet - Item Set  acquireCount long  1 ~ 9223372036854775805 Acquisition quantity Example Master Data Buff Application Condition Model Gs2Inventory:InventoryModel Inventory Model Example Master Data Gs2Inventory:ItemModel Item Model Example Master Data Gs2Inventory:ConsumeItemSet Consume Item Sets Reduces the quantity of the specified item in the requesting user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items to consume the requested amount. Target fields for buff application consumeCount ItemSet - Item Set  consumeCount long  1 ~ 9223372036854775805 Consumption quantity Example Master Data Buff Application Condition Model Gs2Inventory:InventoryModel Inventory Model Example Master Data Gs2Inventory:ItemModel Item Model Example Master Data Gs2Inventory:ConsumeItemSetByUserId Consume Item Sets by specifying the user ID Reduces the quantity of the specified item in the given user’s inventory. If itemSetName is specified, consumption targets that specific stack only. Without it, items are consumed across all stacks of that item type. When an item set’s count reaches zero, it is automatically deleted. Returns an Insufficient error if the user does not have enough items. Target fields for buff application consumeCount ItemSet - Item Set  consumeCount long  1 ~ 9223372036854775805 Consumption quantity Example Master Data Buff Application Condition Model Gs2Inventory:InventoryModel Inventory Model Example Master Data Gs2Inventory:ItemModel Item Model Example Master Data Gs2Inventory:AcquireSimpleItemsByUserId Acquire Simple Items by specifying a user ID Adds items to the user’s simple inventory using a batch of acquire counts. Multiple items can be acquired in a single atomic operation — the acquireCounts array specifies the item name and quantity for each item to acquire. Unlike regular item sets, simple items have no capacity limits, stacking limits, or expiration. Target fields for buff application acquireCounts SimpleItem - Simple Item  acquireCounts List  1 ~ 100 items List of acquisition quantities for Simple Items Example Master Data Buff Application Condition Model Gs2Inventory:SimpleInventoryModel Simple Inventory Model Example Master Data Gs2Inventory:SimpleItemModel Simple Item Model Example Master Data Gs2Inventory:ConsumeSimpleItems Consume Simple Items Reduces the quantity of items in the requesting user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails. Returns an Insufficient error if the user does not have enough of any specified item. Target fields for buff application consumeCounts SimpleItem - Simple Item  consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items Example Master Data Buff Application Condition Model Gs2Inventory:SimpleInventoryModel Simple Inventory Model Example Master Data Gs2Inventory:SimpleItemModel Simple Item Model Example Master Data Gs2Inventory:ConsumeSimpleItemsByUserId Consume Simple Items by specifying a user ID Reduces the quantity of items in the specified user’s simple inventory using a batch of consume counts. Multiple items can be consumed in a single atomic operation — if any item has insufficient quantity, the entire operation fails. Target fields for buff application consumeCounts SimpleItem - Simple Item  consumeCounts List  1 ~ 100 items List of consumption quantities of Simple Items Example Master Data Buff Application Condition Model Gs2Inventory:SimpleInventoryModel Simple Inventory Model Example Master Data Gs2Inventory:SimpleItemModel Simple Item Model Example Master Data Gs2Inventory:AcquireBigItemByUserId Acquire Big Item by specifying a user ID Adds the specified quantity to the user’s big item count using arbitrary-precision arithmetic. The acquireCount must be a valid integer string up to 1024 digits; an invalid format will result in an error. If the item does not yet exist, it will be automatically created. A GS2-Script can be configured to execute custom logic when big items are acquired via the namespace settings. Target fields for buff application acquireCount BigItem - Big Item  acquireCount string  ~ 1024 chars Acquisition quantity for a Big Item Integer value strings up to 1024 digits Example Master Data Buff Application Condition Model Gs2Inventory:BigInventoryModel Big Inventory Model Example Master Data Gs2Inventory:BigItemModel Big Item Model Example Master Data Gs2Inventory:ConsumeBigItem Consume Big Items Subtracts the specified quantity from the requesting user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings. Target fields for buff application consumeCount BigItem - Big Item  consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits Example Master Data Buff Application Condition Model Gs2Inventory:BigInventoryModel Big Inventory Model Example Master Data Gs2Inventory:BigItemModel Big Item Model Example Master Data Gs2Inventory:ConsumeBigItemByUserId Consume Big Items by specifying a user ID Subtracts the specified quantity from the specified user’s big item count using arbitrary-precision arithmetic. The consumeCount must be a valid integer string up to 1024 digits. If the current count is insufficient, an Insufficient error is returned and no deduction is made. A GS2-Script can be configured to execute custom logic when big items are consumed via the namespace settings. Target fields for buff application consumeCount BigItem - Big Item  consumeCount string  ~ 1024 chars Consumption quantity of a Big Item Integer value strings up to 1024 digits Example Master Data Buff Application Condition Model Gs2Inventory:BigInventoryModel Big Inventory Model Example Master Data Gs2Inventory:BigItemModel Big Item Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Inventory Buff Reference","url":"/api_reference/inventory/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Action Types of actions that can apply buffs Gs2Limit:CountUp Count-up Increments the requesting user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created with a count of 0 before incrementing. Target fields for buff application maxValue Counter - Current Counter Value  maxValue int 1 ~ 2147483646 Maximum value allowed to count up Example Master Data Buff Application Condition Model Gs2Limit:LimitModel Usage Limit Model Example Master Data Gs2Limit:Counter Current Counter Value Example Master Data Gs2Limit:CountUpByUserId Count-up by specifying a user ID Increments the specified user’s counter by the specified count-up value. If maxValue is specified, the counter will not exceed that limit; an Overflow error is returned if the operation would exceed the maximum. If the counter does not yet exist, it is automatically created. Target fields for buff application maxValue Counter - Current Counter Value  maxValue int 1 ~ 2147483646 Maximum value allowed to count up Example Master Data Buff Application Condition Model Gs2Limit:LimitModel Usage Limit Model Example Master Data Gs2Limit:Counter Current Counter Value Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Limit Buff Reference","url":"/api_reference/limit/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2LoginReward:BonusModel Login Bonus Model Target fields for buff application acquireActions  acquireActions List  1 ~ 10 items List of Acquire Actions List of acquire actions that define the resources granted to the user for this day’s reward. Each action specifies an acquire action (e.g., add items, grant currency) and its request parameters. At least 1 and up to 10 actions can be configured per reward. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2LoginReward:BonusModel Login Bonus Model Example Master Data missedReceiveReliefConsumeActions  missedReceiveReliefConsumeActions List {missedReceiveRelief} == “enabled” [] 0 ~ 10 items Missed Receive Relief Consume Actions List of consume actions that define the cost a user must pay to recover a missed bonus. For example, this can be configured to consume in-game currency or items as the recovery cost. Up to 10 actions can be configured. Only applicable when missedReceiveRelief is enabled. * Enabled only if missedReceiveRelief is “enabled” Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2LoginReward:BonusModel Login Bonus Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-LoginReward Buff Reference","url":"/api_reference/login_reward/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Mission:MissionTaskModel Mission Task Model Target fields for buff application completeAcquireActions  completeAcquireActions List [] 0 ~ 100 items Rewards for mission accomplishment The list of acquire actions executed as rewards when the player receives the mission completion reward. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Mission:MissionGroupModel Mission Group Model Example Master Data Gs2Mission:MissionTaskModel Mission Task Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Mission Buff Reference","url":"/api_reference/mission/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Action Types of actions that can apply buffs Gs2Money:DepositByUserId Deposit balance to wallet by specifying a user ID Adds the specified amount of currency to the wallet for the specified user. If the price is 0, it is treated as free currency; otherwise, it is treated as paid currency. Target fields for buff application count Wallet - Wallet  count int  1 ~ 2147483646 Quantity of premium currency to be granted Example Master Data Buff Application Condition Model Gs2Money:Wallet Wallet Example Master Data Gs2Money:Withdraw Consume balance from wallet Withdraws the specified amount of currency from the wallet for the requesting user. If paidOnly is false, free currency is consumed first, then paid currency. If paidOnly is true, only paid currency is consumed. The response includes the price of the consumed currency. Target fields for buff application count Wallet - Wallet  count int  1 ~ 2147483646 Quantity of premium currency to be consumed Example Master Data Buff Application Condition Model Gs2Money:Wallet Wallet Example Master Data Gs2Money:WithdrawByUserId Consume balance from wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Target fields for buff application count Wallet - Wallet  count int  1 ~ 2147483646 Quantity of premium currency to be consumed Example Master Data Buff Application Condition Model Gs2Money:Wallet Wallet Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Money Buff Reference","url":"/api_reference/money/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Action Types of actions that can apply buffs Gs2Money2:DepositByUserId Deposit balance to Wallet by specifying a user ID Adds the specified deposit transactions to the wallet for the specified user. An event log is recorded for each deposit transaction. Target fields for buff application count DepositTransaction - Deposit Transaction  count int  0 ~ 2147483646 Quantity of premium currency The number of virtual currency units in this deposit. Decreases as currency is withdrawn from the wallet. Example Master Data Buff Application Condition Model Gs2Money2:Wallet Wallet Example Master Data Gs2Money2:Withdraw Withdraw balance from wallet Withdraws the specified amount of currency from the wallet for the requesting user. If paidOnly is false, free currency is consumed first, then paid currency. If paidOnly is true, only paid currency is consumed. Target fields for buff application withdrawCount Wallet - Wallet  withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed Example Master Data Buff Application Condition Model Gs2Money2:Wallet Wallet Example Master Data Gs2Money2:WithdrawByUserId Withdraw balance from Wallet by specifying a user ID Withdraws the specified amount of currency from the wallet for the specified user. If paidOnly is false, free currency is consumed first, then paid currency. Target fields for buff application withdrawCount Wallet - Wallet  withdrawCount int  1 ~ 2147483646 Quantity of premium currency to be consumed Example Master Data Buff Application Condition Model Gs2Money2:Wallet Wallet Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Money2 Buff Reference","url":"/api_reference/money2/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Quest:QuestModel Quest Model Target fields for buff application completeAcquireActions  completeAcquireActions List [] 0 ~ 10 items Complete Acquire Actions Acquire actions executed as rewards when the quest is completed with this content variation. These define the actual rewards the player receives upon clearing the quest. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Quest:QuestGroupModel Quest Group Model Example Master Data Gs2Quest:QuestModel Quest Model Example Master Data firstCompleteAcquireActions  firstCompleteAcquireActions List [] 0 ~ 10 items First Completion Acquire Actions List of acquire actions executed only on the first completion of this quest. These are bonus rewards granted in addition to the normal completion rewards, useful for first-clear bonuses. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Quest:QuestGroupModel Quest Group Model Example Master Data Gs2Quest:QuestModel Quest Model Example Master Data failedAcquireActions  failedAcquireActions List [] 0 ~ 100 items Failed Acquire Actions Acquire actions executed when the quest fails. Used to provide consolation rewards or partial refunds of the quest participation cost upon failure. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Quest:QuestGroupModel Quest Group Model Example Master Data Gs2Quest:QuestModel Quest Model Example Master Data verifyActions  verifyActions List [] 0 ~ 10 items List of Verify Actions List of verify actions that serve as preconditions for starting this quest. All verify actions must pass before the quest can begin. Used to enforce requirements such as level checks or item possession. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Quest:QuestGroupModel Quest Group Model Example Master Data Gs2Quest:QuestModel Quest Model Example Master Data consumeActions  consumeActions List [] 0 ~ 10 items List of Acquire Actions Consume actions executed as the cost of starting this quest. These are consumed when the quest begins, such as stamina or currency costs. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Quest:QuestGroupModel Quest Group Model Example Master Data Gs2Quest:QuestModel Quest Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Quest Buff Reference","url":"/api_reference/quest/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Showcase:DisplayItem Displayed Item Target fields for buff application acquireActions  acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards. Executed after all consume actions complete successfully. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:Showcase Showcase Example Master Data Gs2Showcase:DisplayItem Displayed Item Example Master Data verifyActions  verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before the purchase. All verify actions must pass before consume and acquire actions are processed. Can be used to check purchase eligibility conditions. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:Showcase Showcase Example Master Data Gs2Showcase:DisplayItem Displayed Item Example Master Data consumeActions  consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price. Can include GS2-Limit CountUp actions to control purchase limits for sales item groups. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:Showcase Showcase Example Master Data Gs2Showcase:DisplayItem Displayed Item Example Master Data Gs2Showcase:RandomDisplayItemModel Items that can be displayed in a Random Showcase Target fields for buff application acquireActions  acquireActions List [] 1 ~ 100 items List of Acquire Actions Actions that grant resources as purchase rewards for this Random Displayed Item. Executed as acquire actions in the transaction. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:RandomShowcase Random Showcase Example Master Data Gs2Showcase:RandomDisplayItemModel Items that can be displayed in a Random Showcase Example Master Data verifyActions  verifyActions List [] 0 ~ 10 items List of Verify Actions Precondition checks executed before purchasing this Random Displayed Item. All verify actions must pass before consume and acquire actions are processed. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:RandomShowcase Random Showcase Example Master Data Gs2Showcase:RandomDisplayItemModel Items that can be displayed in a Random Showcase Example Master Data consumeActions  consumeActions List [] 0 ~ 10 items List of Consume Actions Actions that consume resources as the purchase price for this Random Displayed Item. Executed as consume actions in the transaction. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:RandomShowcase Random Showcase Example Master Data Gs2Showcase:RandomDisplayItemModel Items that can be displayed in a Random Showcase Example Master Data stock  stock int  1 ~ 2147483646 Stock The maximum number of times this item can be drawn across all rotations. Once stock reaches zero, the item is excluded from future draws. Stock is consumed when the item is selected during a rotation draw. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Showcase:RandomShowcase Random Showcase Example Master Data Gs2Showcase:RandomDisplayItemModel Items that can be displayed in a Random Showcase Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Showcase Buff Reference","url":"/api_reference/showcase/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2SkillTree:NodeModel Node Model Target fields for buff application releaseVerifyActions  releaseVerifyActions List [] 0 ~ 10 items List of Release Verify Actions List of verify actions executed before releasing this node to check whether the conditions are satisfied. For example, can verify that the player has a certain level or possesses a specific item. If any verify action fails, the node release is rejected. Maximum 10 actions. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2SkillTree:NodeModel Node Model Example Master Data releaseConsumeActions  releaseConsumeActions List [] 1 ~ 10 items Release Consume Actions List of consume actions executed when releasing this node, representing the cost to unlock it. These actions are also used to calculate the return acquire actions: each consume action is reverted at the restrain return rate when the node is restrained. At least 1 consume action is required. Maximum 10 actions. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2SkillTree:NodeModel Node Model Example Master Data restrainReturnRate  restrainReturnRate float 1.0 0.0 ~ 1.0 Restrain Return Rate The rate at which consumed resources are refunded when this node is restrained (reverted to unreleased state). A value of 1.0 means full refund, 0.5 means half refund, and 0.0 means no refund. Defaults to 1.0 (full refund). Valid range: 0.0 to 1.0. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2SkillTree:NodeModel Node Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-SkillTree Buff Reference","url":"/api_reference/skill_tree/buff/"},{"content":"Note See BuffEntryModel for more information on the buff entry model. Models Target model types available for buff application Gs2Stamina:Stamina Stamina Target fields for buff application maxValue  maxValue int  1 ~ 2147483646 Maximum Stamina The per-user maximum stamina value, resolved from the StaminaModel and optionally overridden by a MaxStaminaTable based on the player’s GS2-Experience rank. When overflow is disabled, this value is floored at initialCapacity. When overflow is enabled, it is capped at maxCapacity. Natural time-based recovery stops at this value. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data recoverIntervalMinutes  recoverIntervalMinutes int 1 ~ 2147483646 Stamina Recovery Interval (Minutes) The per-user recovery interval in minutes, resolved from the StaminaModel and optionally overridden by a RecoverIntervalTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverIntervalMinutes. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data recoverValue  recoverValue int 1 ~ 2147483646 Stamina Recovery Amount The per-user recovery amount per tick, resolved from the StaminaModel and optionally overridden by a RecoverValueTable based on the player’s GS2-Experience rank. If no table is configured, the value falls back to the model’s default recoverValue. Example Master Data rate specifies the multiplier applied to the target field. Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data Action Types of actions that can apply buffs Gs2Stamina:ConsumeStamina Consume Stamina Deducts the specified amount from the current stamina value. Returns an Insufficient error if the current stamina value is less than the consume amount. Target fields for buff application consumeValue Stamina - Stamina  consumeValue int  1 ~ 2147483646 Amount of stamina consumed Example Master Data Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data Gs2Stamina:ConsumeStaminaByUserId Consume Stamina by specifying a user ID Deducts the specified amount from the current stamina value for the given user. Returns an Insufficient error if the current stamina value is less than the consume amount. Target fields for buff application consumeValue Stamina - Stamina  consumeValue int  1 ~ 2147483646 Amount of stamina consumed Example Master Data Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data Gs2Stamina:RecoverStaminaByUserId Recover Stamina by specifying a user ID Recovers stamina by the specified amount up to the maximum capacity. If the recovery causes the value to exceed the maximum and overflow mode is enabled, the excess is tracked as an overflow value. Target fields for buff application recoverValue Stamina - Stamina  recoverValue int  1 ~ 2147483646 Amount of stamina recovery Example Master Data Buff Application Condition Model Gs2Stamina:StaminaModel Stamina Model Example Master Data","lang":"en","section":"api_reference","summary":"Describes the fields within models/actions whose parameters can be adjusted when applying buffs with GS2-Buff, and how to configure the scope in which those buffs are applied.\n","title":"GS2-Stamina Buff Reference","url":"/api_reference/stamina/buff/"},{"content":"Automating master data updates can reduce human error and speed up the development cycle. Automation Flow The general automation flow is as follows: Data Creation : Create master data using Excel, Google Sheets, CSV, etc. Conversion : Convert from spreadsheets to GS2 master data format (JSON). Commit : Commit the converted JSON or GS2-Deploy template to a Git repository. Deployment : CI tools (GitHub Actions, CircleCI, etc.) detect changes and reflect them in GS2. Automating Deployment Using GS2-Deploy If you embed master data in a GS2-Deploy template, you can reflect changes by updating the GS2-Deploy stack from your CI. Example for GitHub Actions: jobs: deploy: runs-on: ubuntu-latest steps: - uses: actions/checkout@v2 - name: GS2 Deploy run: | # Use gs2-cli or similar to update the stack gs2-cli deploy update-stack --stack-name master-data --template-file template.yaml Using Export/Import of the Management Console By calling the API to update the CurrentItemModelMaster of each microservice, you can reflect the contents of the JSON file. Recommendations Test in a Verification Environment : Always deploy to a project/namespace for verification and confirm operation before reflecting changes in the production environment. Validation : We strongly recommend using scripts to check data consistency (ID duplication checks, existence checks for related resources, etc.) before deployment.","lang":"en","section":"articles","summary":"Automatic master data updates using GitHub Actions, etc.\n","title":"CI/CD for Master Data","url":"/articles/master_data/cicd/"},{"content":"Since GS2 uses a pay-as-you-go pricing model, usage fees can vary significantly depending on the game’s design. This section explains key design points to keep costs down while maintaining performance. 1. Reduction of API Call Count A large portion of GS2 fees is determined by the number of API requests. Utilize SDK Caching Mechanism The GS2 SDK has a built-in caching mechanism. When the same data is retrieved multiple times in a short period, it is designed to return the data from the cache without sending a request to the server. Use high-level APIs (access via Domain objects) whenever possible when using Future or Async versions of SDK methods. Batch Retrieval and Updates For example, when retrieving the quantity of multiple items, it is more cost-effective to retrieve the entire inventory at once rather than calling the API for each item individually. 2. Proper Resource Management with GS2-Deploy If unnecessary namespaces or resources remain, small storage fees or management costs may continue to accrue. For development or verification environments, you can clean up related resources all at once by deleting the GS2-Deploy stack when they are no longer needed. 3. Execution Efficiency of GS2-Script GS2-Script execution fees vary depending on execution time. Efficient Code : Improve the efficiency of the Lua scripts themselves to reduce execution time, such as by avoiding unnecessary API calls within loops. Minimize External Communication : External communication such as http.get can significantly increase execution time. Note that while memory usage does not directly affect fees, there is a limit on the available memory capacity. 4. Leveraging Logs and Analytics By associating GS2-Log in the namespace settings of each microservice, you can collect access logs (request and response content) for each microservice. This allows for detailed analysis of whether specific features are generating more requests than expected and which APIs are contributing to costs, helping you optimize your application.","lang":"en","section":"articles","summary":"Design guide for optimizing GS2 usage fees.\n","title":"Cost Optimization","url":"/articles/tech/cost/"},{"content":"","lang":"en","section":"design_knowledge","summary":"This section summarizes knowledge about game design that is not directly related to Game Server Services.","title":"Game Design Knowledge","url":"/design_knowledge/"},{"content":"Learn from what successful titles do as a matter of course.","lang":"en","section":"design_knowledge","summary":"Learn from past successes","title":"Learning from Success","url":"/design_knowledge/success/"},{"content":"We should learn from our failures, not our successes! Let’s design games while thinking about what we can do to prevent ourselves from making the same mistakes.","lang":"en","section":"design_knowledge","summary":"learn what went wrong and what to do about it based on past failures","title":"Learning from Failure","url":"/design_knowledge/fail/"},{"content":"If you are celebrating the first anniversary of the launch of a game, the 100th day, or even the 2.5(!?) anniversary of a game, celebrate it as soon as you can. If there is a good time to celebrate, celebrate it actively. At these times, we can offer various initiatives such as “special login bonuses”, “10 free gacha draws every day”, “halving the stamina required to progress in quests”, “doubling the amount of experience gained” and so on. By making a big deal of it, we can make people think, “Oh, it’s been a year since the game was launched. I only played it for the first three months, but it seems like a good deal if I play it again now, so I might give it another try.” If the game is well-loved, players can expect to pay more than usual for it out of a sense of support.","lang":"en","section":"design_knowledge","summary":"anniversary event is a big deal","title":"Anniversary Event","url":"/design_knowledge/success/anniversary_event/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"API Reference","url":"/api_reference/"},{"content":"While it is important to have a system that changes every day to create a routine, weekly changes are also important to keep people playing the game for a year. Nevertheless, there are games that have cycles of a week or more. It is also important to consider how often the changes can be made in a way that fits with the development resources available, and then design the game accordingly. However, it is important to make sure to make changes once every two weeks, even if they are small. Even a small change in the game is important for daily players. Here are some examples of changes that are commonly made the addition of a new character new scenarios/quests adding limited time scenarios/quests There are two types of directions. 1 and 2 are updates to the overall game. 3 is to provide content that can only be played now, such as seasonal content or collaboration scenarios with other works to attract new players. It is not necessary to do all of these every week, but it is realistic to have a cycle where new characters are added every three weeks, staggered by one week.","lang":"en","section":"design_knowledge","summary":"bring something new to the game every week!","title":"Bringing Change Every Week","url":"/design_knowledge/success/bring_change_game_every_week/"},{"content":"Gacha is an evil system where you don’t know how much you have to pay to actually get a character. There was a time when I thought so too. However, here are some examples of failures that completely negate that. A certain game decided to sell new characters for 10 USD. Since the general rate for gachas is 3 USD per gacha, it is an exceptional deal to get a fixed character for a little over three times the price. However, this initiative was not well received by players who had not paid. Unpaid players use in-game currency obtained from event rewards to draw gachas and get new characters. In other words, these players will never be able to get this character. I understand the feeling of the management side, “You didn’t pay for it, so it must happen.” However, we also need to remember that non-paying players make up 90% of the game players. When selling characters directly, it seems safer to make them available to non-paying players through other means in addition.","lang":"en","section":"design_knowledge","summary":"buy character directly","title":"Buy a character","url":"/design_knowledge/fail/purchase_character/"},{"content":"In a type of game that requires players to play laps to collect materials used for training, managing the emission of in-game resources is important. Particular care should be taken when determining the amount of resources that may be paid out in various content, such as experience and in-game currency. Players are smart, and if they know that they can collect resources efficiently in a particular content, they will repeat that behavior. And this can lead to the destruction of the in-game economy and the disruption of game balance. If you take actions to correct this, such as revising the resource drain downward, you will inevitably be angered by the players themselves as a nerf. When designing such a game, for content that allows players to continue playing as long as their time permits with no limit on the number of times they can play, the amount of resources to be drained per hour should be determined in advance. In-game currency will only pay out “1000G/hour” no matter how the game is played. Once you have decided that this is the case, you can divide this number by the amount of time you play the content to determine the appropriate amount the content should drain. If you have stamina, you can determine “1000G / hourly stamina recovery” as the amount of resources gained per hour of stamina consumed, and determine the appropriate amount of resources to discharge based on the amount of stamina consumed by the content. By extending this thinking, content can be prepared based on a concept such as “You can only try once a day, but you can gain resources for 24 hours” to raise the amount of resources gained by players who can only play for short periods of time. Finally, if the concept is to allow players to develop their characters by playing for 720 hours (one month), then a growth element that requires resources of “resource drain per hour * 720” can be prepared.","lang":"en","section":"design_knowledge","summary":"Treat your content equally by determining the resource drain per hour!","title":"Determine resource emissions per hour","url":"/design_knowledge/success/determine_resource_emissions_per_hour/"},{"content":"In order to get players to play for a long period of time, it is better not to let them play too much in a short period of time. Unlimited play will not only widen the gap between long-time players and short-time players, but also If the game is allowed unlimited play, it will not only widen the gap between long-time players and short-time players, but it will also make it necessary to listen to two voices: one from long-time players asking for something to be done about the lack of content, and one from short-time players asking for something other than lack of content. By narrowing down the issues that developers need to address, they can focus their resources on developing games that will satisfy a large number of players. A common method used to keep players from playing for long periods of time is “stamina. Stamina is an in-game resource that can be recovered over time in real time without having to pay for it. By making the game consume this resource in order to play, the number of plays per hour can be limited. Another approach is to cap the total amount of resources that can be obtained, although they can be played as much as desired. Both reduce the disparity between players by allowing the developer to control the amount of resources per hour that a player can acquire. The former is superior in that it is expected to increase the likelihood that players will start the game again by having them exit the game with the feeling that they still want to play. The trick to a long-running game is to minimize the time required to use up all the stamina earned each day. A life cycle of playing for 15 minutes a day is less demanding on the player than a life cycle of playing for an hour a day, and this will increase the probability that the player will continue to play.","lang":"en","section":"design_knowledge","summary":"don't let them play too much in a short period of time to let them play for a long time","title":"Don't let them play too much","url":"/design_knowledge/success/dont_play_too_much/"},{"content":"To encourage people to play every day of the week, it is effective to make it meaningful to play tomorrow instead of today. A good example of this would be “day-of-week quests”. On Mondays, there are “wind materials” and on Tuesdays, “fire materials”. Tuesday: “Materials for Fire” Wednesday: “Materials for Water” Thursday: “Materials for Ground” Friday: “In-game currency” Saturday: “Materials for Dark” Sunday: “Materials for Light” In this way, quests are prepared for each day of the week, and the rewards for these quests are materials for training characters with specific attributes. This will increase the likelihood that players will log in the next day if they want to train a character with the fire attribute but do not have the materials and today is Monday.","lang":"en","section":"design_knowledge","summary":"make each day of the week unique to keep you motivated to play every day","title":"Feature on a day of the week","url":"/design_knowledge/success/make_days_of_week_uniqueness/"},{"content":"The gacha effects should be spectacular. However, if you lie about it, you risk being judged by the law. In one game, an item was taken out of a box as part of the gacha performance. However, there was a large discrepancy between the item in the box during the production and the actual probability of ejection. The appearance of the box contained many rare items and it looked as if the rare items could be easily obtained. This may fall under the category of “misrepresentation of quality” as defined by Japan’s Act Against Unjustifiable Premiums and Misleading Representations, which is an act of trying to make a product look better than it actually is. This was a firestorm. In the end, there was no result on whether the law was actually violated in this case, but there is no doubt that there is at least some risk. Please be careful when creating your production.","lang":"en","section":"design_knowledge","summary":"Designing a gacha effects","title":"Gacha effects","url":"/design_knowledge/fail/gacha_effect/"},{"content":"Introduction to Microservices / Account","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Account","title":"Reference of GS2-Account","url":"/api_reference/account/"},{"content":"Introduction to Microservices / AdReward","lang":"en","section":"api_reference","summary":"Introduction to Microservices / AdReward","title":"Reference of GS2-AdReward","url":"/api_reference/ad_reward/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Auth","url":"/api_reference/auth/"},{"content":"Introduction to Microservices / Buff","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Buff","title":"Reference of GS2-Buff","url":"/api_reference/buff/"},{"content":"Introduction to Microservices / Chat","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Chat","title":"Reference of GS2-Chat","url":"/api_reference/chat/"},{"content":"Introduction to Microservices / Datastore","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Datastore","title":"Reference of GS2-Datastore","url":"/api_reference/datastore/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Deploy","url":"/api_reference/deploy/"},{"content":"Introduction to Microservices / Dictionary","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Dictionary","title":"Reference of GS2-Dictionary","url":"/api_reference/dictionary/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Distributor","url":"/api_reference/distributor/"},{"content":"Introduction to Microservices / Enchant","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Enchant","title":"Reference of GS2-Enchant","url":"/api_reference/enchant/"},{"content":"Introduction to Microservices / Enhance","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Enhance","title":"Reference of GS2-Enhance","url":"/api_reference/enhance/"},{"content":"Introduction to Microservices / Exchange","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Exchange","title":"Reference of GS2-Exchange","url":"/api_reference/exchange/"},{"content":"Introduction to Microservices / Experience","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Experience","title":"Reference of GS2-Experience","url":"/api_reference/experience/"},{"content":"Introduction to Microservices / Formation","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Formation","title":"Reference of GS2-Formation","url":"/api_reference/formation/"},{"content":"Tip GS2-Freeze fixes the GS2 API version used by games and provides a mechanism to update the version at any time. This is an enterprise feature and is not a widely available feature. Please contact support for more information.","lang":"en","section":"api_reference","summary":"Tip GS2-Freeze fixes the GS2 API version used by games and provides a mechanism to update the version at any time. This is an enterprise feature and is not a widely available feature.\nPlease contact support for more information.","title":"Reference of GS2-Freeze","url":"/api_reference/freeze/"},{"content":"Introduction to Microservices / Friend","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Friend","title":"Reference of GS2-Friend","url":"/api_reference/friend/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Gateway","url":"/api_reference/gateway/"},{"content":"Introduction to Microservices / Grade","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Grade","title":"Reference of GS2-Grade","url":"/api_reference/grade/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Guard","url":"/api_reference/guard/"},{"content":"Introduction to Microservices / Guild","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Guild","title":"Reference of GS2-Guild","url":"/api_reference/guild/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Identifier","url":"/api_reference/identifier/"},{"content":"Introduction to Microservices / Idle","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Idle","title":"Reference of GS2-Idle","url":"/api_reference/idle/"},{"content":"Introduction to Microservices / Inbox","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Inbox","title":"Reference of GS2-Inbox","url":"/api_reference/inbox/"},{"content":"Introduction to Microservices / Inventory","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Inventory","title":"Reference of GS2-Inventory","url":"/api_reference/inventory/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-JobQueue","url":"/api_reference/job_queue/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Key","url":"/api_reference/key/"},{"content":"Introduction to Microservices / Limit","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Limit","title":"Reference of GS2-Limit","url":"/api_reference/limit/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Lock","url":"/api_reference/lock/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Log","url":"/api_reference/log/"},{"content":"Introduction to Microservices / LoginReward","lang":"en","section":"api_reference","summary":"Introduction to Microservices / LoginReward","title":"Reference of GS2-LoginReward","url":"/api_reference/login_reward/"},{"content":"Introduction to Microservices / Lottery","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Lottery","title":"Reference of GS2-Lottery","url":"/api_reference/lottery/"},{"content":"Introduction to Microservices / Matchmaking","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Matchmaking","title":"Reference of GS2-Matchmaking","url":"/api_reference/matchmaking/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-MegaField","url":"/api_reference/mega_field/"},{"content":"Introduction to Microservices / Mission","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Mission","title":"Reference of GS2-Mission","url":"/api_reference/mission/"},{"content":"Introduction to Microservices / Money Warning GS2-Money2 is now available. Please use GS2-Money2 for new users unless there is a special reason.","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Money\nWarning GS2-Money2 is now available.\nPlease use GS2-Money2 for new users unless there is a special reason.","title":"Reference of GS2-Money","url":"/api_reference/money/"},{"content":"Introduction to Microservices / Money2 Tip GS2-Money2 is a microservice that, as the name suggests, corresponds to version 2. See GS2-Money for documentation on previous versions.","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Money2\nTip GS2-Money2 is a microservice that, as the name suggests, corresponds to version 2.\nSee GS2-Money for documentation on previous versions.","title":"Reference of GS2-Money2","url":"/api_reference/money2/"},{"content":"Introduction to Microservices / News","lang":"en","section":"api_reference","summary":"Introduction to Microservices / News","title":"Reference of GS2-News","url":"/api_reference/news/"},{"content":"Introduction to Microservices / Quest","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Quest","title":"Reference of GS2-Quest","url":"/api_reference/quest/"},{"content":"Introduction to Microservices / Ranking Warning GS2-Ranking2 is now available. Please use GS2-Ranking2 for new users unless there is a special reason.","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Ranking\nWarning GS2-Ranking2 is now available.\nPlease use GS2-Ranking2 for new users unless there is a special reason.","title":"Reference of GS2-Ranking","url":"/api_reference/ranking/"},{"content":"Introduction to Microservices / Ranking2 Tip GS2-Ranking2 is a microservice that, as the name suggests, corresponds to version 2. See GS2-Ranking for documentation on previous versions.","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Ranking2\nTip GS2-Ranking2 is a microservice that, as the name suggests, corresponds to version 2.\nSee GS2-Ranking for documentation on previous versions.","title":"Reference of GS2-Ranking2","url":"/api_reference/ranking2/"},{"content":"Introduction to Microservices / Realtime","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Realtime","title":"Reference of GS2-Realtime","url":"/api_reference/realtime/"},{"content":"Introduction to Microservices / Schedule","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Schedule","title":"Reference of GS2-Schedule","url":"/api_reference/schedule/"},{"content":"","lang":"en","section":"api_reference","summary":"","title":"Reference of GS2-Script","url":"/api_reference/script/"},{"content":"Introduction to Microservices / SeasonRating","lang":"en","section":"api_reference","summary":"Introduction to Microservices / SeasonRating","title":"Reference of GS2-SeasonRating","url":"/api_reference/season_rating/"},{"content":"Introduction to Microservices / SerialKey","lang":"en","section":"api_reference","summary":"Introduction to Microservices / SerialKey","title":"Reference of GS2-SerialKey","url":"/api_reference/serial_key/"},{"content":"Introduction to Microservices / Showcase","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Showcase","title":"Reference of GS2-Showcase","url":"/api_reference/showcase/"},{"content":"Introduction to Microservices / SkillTree","lang":"en","section":"api_reference","summary":"Introduction to Microservices / SkillTree","title":"Reference of GS2-SkillTree","url":"/api_reference/skill_tree/"},{"content":"Introduction to Microservices / Stamina","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Stamina","title":"Reference of GS2-Stamina","url":"/api_reference/stamina/"},{"content":"Introduction to Microservices / StateMachine","lang":"en","section":"api_reference","summary":"Introduction to Microservices / StateMachine","title":"Reference of GS2-StateMachine","url":"/api_reference/state_machine/"},{"content":"Introduction to Microservices / Version","lang":"en","section":"api_reference","summary":"Introduction to Microservices / Version","title":"Reference of GS2-Version","url":"/api_reference/version/"},{"content":"GSL is a state machine definition language with excellent readability and descriptiveness, but it is not superior in terms of IDE input support and learning cost. CDK can be used to define GSL using various programming languages. CDK details Start defining a state machine Use the following syntax to start a state machine definition State machine definition State definition Task SubStateMachineTask WaitTask PassTask ErrorTask Register to the stack Full sample","lang":"en","section":"api_reference","summary":"extension syntax for defining GS2 States Language in CDK","title":"GS2 States Language Definition Extension","url":"/api_reference/state_machine/deploy/extention/"},{"content":"While the game will be packed with a variety of elements, there will always be features and content that are underutilized. Such content should be improved, not neglected. Reasons why content is unpopular can be categorized as follows Boring Rewards are not attractive Takes too much time Boring It is also important to discard boring content gracefully. It is also important to make a decision to shift the cost of maintaining such content to other functions. Rewards are not attractive It is also a common pattern that content itself is not bad, but the rewards are not attractive, so people do not play. It takes a lot of human resources to modify the content. As an easy approach to start with, try to increase the chances of players coming into contact with the content by making the rewards they get from the content more appealing. Takes too much time If you have content that is unpopular even though the content is not bad and the rewards are not bad, think about the time required to play that content. If the time required to play the content or the number of operations is too high Maybe you should rethink the play style of the content. You may be able to make the content playable in a shorter amount of time, or you may be able to keep the play time the same but add an autoplay function and reduce the number of operations to get players to touch the content.","lang":"en","section":"design_knowledge","summary":"Identify unpopular content and improve it!","title":"Improve unpopular content","url":"/design_knowledge/success/improve_unpopular_content/"},{"content":"In the course of long-term operation of a game, more and more powerful enemies will be added to the game. In one game, characters are developed through about an hour of gameplay per cycle, and The game had a specification that allowed players to play a game mode in which they could compete with other players using the character that they had developed. A new mode has been added to the character development part of the game, which allows players to develop characters with a different parameter balance than before. The new mode allowed players to training characters with one out of five parameters 30% higher than before. Players will be looking at this content and desperately trying to find a way to take advantage of this mode. Items were also added to make training in the new mode more efficient, so players obtained them through a gacha and took on the new mode. Eventually, a player who had succeeded in developing a character with the maximum parameters in the new mode appeared and said, “Not as strong as the numbers.” Behind the scenes, The developers were conflicted because to make all existing trained characters a thing of the past would be to negate the efforts of past players. So the developers, twisting their minds, decided to make it so that although the numerical value would be 30% larger, the actual formula would only affect 1/8th for the portion of the maximum increase. By doing this, they tried to reduce the difference from characters that had been developed in the past. However, this was discovered by players, who criticized them, saying that they thought they had grown 30% stronger, when in fact they had grown only 3.75% stronger. The developers must have thought it was a good idea to introduce a formula to control inflation, but it backfired on them. Although the new mode gives a weaker impression to players, it would have been better if the parameters had been increased by 3.75% instead of 30% in a straightforward manner.","lang":"en","section":"design_knowledge","summary":"inflation control specification","title":"Inflation Control","url":"/design_knowledge/fail/inflation_control/"},{"content":"Case Study One game for smartphones was created by porting a game for console game. The game was released with mini-games included in the home console game as the main content, with the mini-games sold as additional content. The console game had over 50 mini-games, from which five were selected at launch, two of which were made available for free. Each mini-game will be sold for 5 USD worth of in-game currency. However, immediately after launch, server failures continued, and players were repeatedly given 1 USD worth of in-game currency as an apology. Then, on the fifth outage, the developers were faced with a major decision. If they distributed 1 USD worth of charged currency here, “a large number of players would be able to obtain one of the only three additional contents for free.” Even if the apology amount is lowered, it is difficult to do so because the unit of currency is 1 USD = 1 piece. So, the developer stopped apologizing for the failure and acted as if nothing had happened. By the time the outage settled down, players had left, and those who remained were bored and left because no new mini-games had been added since the initial implementation. Looking back Now, there are many problems with this case study. Lack of understanding of the metagame The first is a lack of proper understanding of the metagame. If the main game is sold in installments, there is no need to dress it up as a Game as a Service. Adding main content takes time Adding content = adding main games, and adding content takes too much time and cost. As a result, we want changes in the game several times a month in an operational game, but we could not make changes because it takes more than a month to add content. There is nothing to do every day The game ends when you get bored with the main game because the game does not provide a game cycle where you have to cobble together every day in order to enhance the main game. The main game is also a mini-game, so players will probably only last a week with this. It is a hole in the bucket. There is no future in promoting and attracting players at this point. Setting the unit of currency to be charged Another problem is the way they set the unit of currency. By setting the currency at 1 USD = 1 piece when it is generally set at 1 Cent = 1 or 2 Cents = 1 piece, we have made it more difficult to make a business decision to distribute the currency with an apology to the players. Billing limits are set With three types of content costing 5 USD, 15 USD is the maximum amount of sales that can be obtained from a single player. Let’s assume that the percentage of game players who pay for the game is 5%, and that they purchase an average of 1.5 additional contents. Then, if 10,000 people play the game, 500 of them will pay, and if they purchase an average of 7.5 USD worth of content, the monthly sales will be 35,000 USD. If you need 100,000 USD per month to maintain a development team to develop additional content, you need 30,000 new players each month. To get 30,000 new players, you have to do a good amount of PR, so we can see that this game will not make money even before it launches.","lang":"en","section":"design_knowledge","summary":"problems caused by lack of content","title":"Insufficient content","url":"/design_knowledge/fail/lack_of_content/"},{"content":"A login bonus is an effective way to increase player retention. If players can receive in-game items just by logging in every day, they are more likely to start the game anyway. Here are some mistakes that are often made with such login bonuses. Thank you for logging in every day For example, when preparing a login bonus for January, let’s say you want to offer “Log in for 31 days and you will receive a 10-round gacha ticket!”. It is very understandable that we want to encourage players who log in every day, but this is actually a bad idea, because players who fail to log in even once during the period may say, “That’s enough”. A login bonus that is intended to increase retention is a waste of time and money if it causes player retention to suffer. It is recommended to give a big reward for consecutive log-ins on the 20th day, and keep the remaining 10 days of the year to innocuous items.","lang":"en","section":"design_knowledge","summary":"designing a login bonus","title":"Login Bonus","url":"/design_knowledge/fail/login_rewards/"},{"content":"Case study A game had been downloaded more than 5 million times and was highly rated by players. However, such a popular game suddenly decided to terminate its service. The reason was that the meta-game was not designed well enough to allow players to enjoy the game without having to pay for it. This meant that sales did not increase in relation to the increase in players, and the development and management team, as well as the infrastructure costs to provide the service, could not be sustained. Reflection In this case, the service could have continued if the unit price per player could have been raised, but it is reasonable to consider the termination of the service as the result of a reasonable effort that was not accompanied by results. Now, let’s look back at why it was not possible to raise the cost per customer. Meta-game dysfunction Although there was a meta-game in this game, the function to use the results fostered in the meta-game to take advantage of the main game did not function effectively. In other words, although there was a meta-game, there was not much point in training in the meta-game. Then, players could train, so they steadily trained, but there was no motivation to rush to train, and short-time charges were not used. Targeting too many young people The game is very popular among young people, with 60% of players under age. In particular, players under the age of 14 accounted for 1/3 of the total. We did not expect young players to pay for the game, which would inevitably result in a low ARPU. This probably created a bad situation where the number of players increased and infrastructure costs were heavy, but sales did not increase.","lang":"en","section":"design_knowledge","summary":"about the problem of low sales per player","title":"Low ARPU","url":"/design_knowledge/fail/arpu_too_low/"},{"content":"There was a fraud in which a large number of in-game payments were made by a business partner in order to make the game seem more exciting at the time of release. This was done in order to get the game to the top of the sales ranking and attract new players who saw the game. These transactions were not visible to the outside world, but were brought to light by a whistleblower. However, although the amount of money that the company illegally manipulated sales from the information they disclosed was not small, it did not seem to be large enough to affect the results of the rankings. Although there has been no mention of such a conclusion being reached in this case, it is important not to imitate such an act, as it could be considered window dressing.","lang":"en","section":"design_knowledge","summary":"Manipulation of Sales Chart","title":"Manipulation of Sales Chart","url":"/design_knowledge/fail/chart_manipulation/"},{"content":"This feature is often implemented in games under a name such as “expedition”. This is an element that rewards the quests by waiting for real time to elapse, rather than in-game success or failure. By making it so that players are rewarded after 12 hours of starting a quest, a play cycle can be created in which players log in once a morning and once a night, or even once a day. Since less effort is required to send a character on an expedition, it is easy to get people to play every day.","lang":"en","section":"design_knowledge","summary":"require a time lapse to log in again","title":"Request passage of time","url":"/design_knowledge/success/require_passage_of_time/"},{"content":"This is a case study of a game developer who made a mistake with the content of the Terms of Service, which tends to be left up to the legal team. In a certain game, the personal information to be collected in the terms of service was strange. For some reason, “bank account” and “my number (Japanese social security number)” were listed among the information to be collected. Furthermore, since the game was developed by a developer outside of Japan, the game was spread on social networks as if it were “espionage?”. Later, the Terms of Use was revised to be better, with the explanation that the content had been appropriated from another application, but it would certainly be better if such problems did not occur. If it is the content of the game that is causing the flames, but the wording of the terms of use is causing the flames, I think this is the most unfortunate thing that can happen to a developer who has spent years making a game.","lang":"en","section":"design_knowledge","summary":"contents of terms of use","title":"Terms of Use","url":"/design_knowledge/fail/collection_of_personal_information/"},{"content":"A quest that can be attempted only once every day at a specific time (e.g., from 7:00 PM to 8:00 PM). The reward for this quest should be set to be attractive. It is also useful to combine mobile push notifications to notify players that they can save money if they play the game now.","lang":"en","section":"design_knowledge","summary":"a quest that can be attempted only at a specific time each day","title":"Time Limited Quest","url":"/design_knowledge/success/time_limited_quest/"},{"content":"Events are designed to deliver surprises to many players, to encourage players who have not played before to play, and to bring back players who have left. We want to give players who have never played before a chance to play, and we also want to bring back players who have left the game. This is a story of an event that went wrong when the prizes were too gorgeous. We had an in-game lotto where the winner would win 1000 USD worth of in-game currency. This event delivered a surprise to many players and seemed like a very good event. However, an anomaly occurred on the day the winning numbers were announced. Players who did not win the lotto voiced their disappointment, saying that they were no longer motivated to play and that it would create a disparity. These voices grew louder and louder through social networks, and they were no longer collected. Eventually, the management tried to resolve the situation by pretending that everyone had won the third prize, but this only caused more confusion. I do not know what the right answer is in this case. I am sure that this is a lesson that we need to control our expectations when we prepare a big prize.","lang":"en","section":"design_knowledge","summary":"the risk of too luxurious event rewards","title":"Too luxurious event rewards","url":"/design_knowledge/fail/too_gorgeous_prizes/"},{"content":"The game was not satisfying the players and they were at their wit’s end. As a result, the decision was made to change the main game to a completely new one. A few months later, a major update with a new main game was implemented. But the players who updated to that version are furious. “The game was more fun before the update.” Whether this is really the case or not, unless things have gotten much better after the update, it is probably an inevitable situation that such voices will be heard. From my point of view as an outsider, I think the decision itself is “not going to happen.” If you are going to leverage, it seems like something with smaller steps would be better.","lang":"en","section":"design_knowledge","summary":"over-leverage","title":"Too much leverage","url":"/design_knowledge/fail/too_much_leverage/"},{"content":"Monitor information such as how much of the resources used for training, such as materials and in-game currency, are held by players, and what is the balance between the amount of resources obtained and consumed. If the balance between resource acquisition and consumption is positive, you should consider content that consumes the resource. If the balance of resource availability/consumption is inversely related, you should consider content that emits the resource. However, if the game balance is designed with resources as valuable, it is preferable to leave the amount of emissions as they are, as intended. Such resources may be discharged as rewards for playing monthly events, which can be a factor that keeps players motivated for a long period of time.","lang":"en","section":"design_knowledge","summary":"Keep track of the amount of resources circulating in the game and maintain a normal in-game economy!","title":"Understand the amount of resources distributed in the game","url":"/design_knowledge/success/understand_amount_of_resources/"}]